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Preface 


With the move of J ava applications to a servlet runtime environment on a 
Web server the access of relational databases on the Web server becomes one 
of the most important topics. 

IBM WebSphere is a set of software products that help customers develop 
and manage high-performance Web sites to ease the transition from simple 
Web publishing to advanced e-business applications. 

VisualAgefor J ava Enterprise is the premier J ava integrated development 
environment that helps customers connect their J ava applications totheir 
enterprise data. VisualAgefor J ava provides an integrated WebSphereTest 
Environment that makes development and deployment of servlets to 
WebSphere fast and easy. 

I n this redbook we descri be many ways of how relational database systems 
can be integrated with the VisualAgefor J ava development environment and 
the WebS ph ere execut i on en vi ron ment . 

First, we descri be the installation of the underlying base products IBM 
WebSphere and VisualAgefor J ava. Next, we descri be the installation and 
setup of the database systems and J DBC drivers for the three relational 
database management systems DB2 Universal Database, Oracle, and 
Microsoft SQL Server. Finally, we provide small programming examples for 
J DBC, data access beans, the Persistence Builder, EnterpriseJ avaBeans, 
WebSphere Studio, User Profiles, Security and Directory Services, and SQLJ . 

This redbook is especially suited for J ava application designers that are 
implementing servlets with relational database access. 
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Part 1 


Introduction to 
IBM WebSphere 
and VisualAge 
for Java 


I n this part we briefly discuss the installation of the two products, 
IBM WebSphere and VisualAge for J ava Enterprise. 
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1 HTTP Server and 
WebSphere 
Application Server 

I n this chapter we describe the I BM HTTP Server and the I BM WebSphere 
Application Server. The functionality of these products will be briefly 
discussed, including a few hints and tips on how to set them up to run your 
servlets inside and outside of the Visual Age for J ava environment. 


Environment 

Theexamples in this book were developed in the following environment: 

□ PCs with Pentium 1 1 450 MHZ processors and 128 M B RAM 

□ MS Windows NT 4.0 service pack 4 

□ Both Netscape Navigator 4.5 and M icrosoft I nternet Explorer 4.0 were 
used interchangeably through the test and usage of different components. 
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IBM HTTP Server 


IBM HTTP Server is a Webserver which shares its base code with the 
Apache Server, with additional enhancements such as the Secure Socket 
Layer (SSL). 


Installation 


IBM HTTP Server Version 1.3.3. 1 was used to run the sample code provided 
in this book. 

Be sure to consider the following during the installation: 

□ Make sure there is a user I D dedicated to be used only by the HTTP 
server. 

□ The user ID must be a member of the Administrator group. 

Once you have created the user I D proceed with the installation. As you step 
through the installation pages enter the user I D created prior to the 
installation into the Information for Service Setup panel. 


Configuration 

To configure the HTTP server you should use the httpd.doc file located under 
<drive>:\Program Files\IBM HTTP Server\conf. You can Customize the HTTP 
Server using the tags in httpd.conf file. Here is a description on some of those 
tags: 

DocumentRoot: Thedirectory wheretheHTTP Server looks for the HTM L 
files. Thedefault set value is <drive>: /Program Files/IBM HTTP Server /htdocs. 

Alias: To create a specific location for your project you can take advantage of 
the Alias tag. This tag can be set to point to any directory where you wish to 
pi ace your HTM L and J SP files. If you want to access files which reside in a 
location other than the DocumentRoot directory, you can use an Alias to do 
this. For example, to be ableto access test.html from a c:\ itsowww directory, 
set Alias /itso/ "C: /itsowww/" in the httpd.conf file. This way, to access the 
test.html filefrom the browser thefollowing U RL should be used: 

http://<server name>/i tso/test .html 

ServerRoot: Thedirectory where the server's configuration, error, and log 
files are kept. 

ServerName: If you observe any problems with the IBM HTTP Server it 
might help to explicitly set the server name to your host name. 
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IBM WebSphere Application Server 

The WebSphere Application Server implements a servlet enginethat 
functions as a plug-in to extend the capabilities of a number of Web servers. 
WebSphere is an application server that enables the "write once, use 
anywhere" concept for servlets. 

WebSphere can work with number of different Web servers, such as: 

□ IBM HTTP Server 

□ Apache Server 1.3.x 

□ Lotus Domino 5.0 

□ Lotus Domino Go Webserver 

□ N etscape E nterpri se Server 

□ Netscape FastTrack Server 

□ M icrosoft I nternet I nformation Server 

All of the samples provided in this book have used the IBM HTTP Server as 
their Web server. 

With a properly coded U RL, client requests to a Web server are passed on to 
the Application Server. The Application Server, in turn, passes the client 
request information to a J ava servlet, which acts on the request information 
and prepares a response that is sent back to the client through the 
Application Server and the Web server. 

A J ava servlet is basically an ordinary piece of J ava code with added 
capabilities provided by APIs in the javax. servlet and \avax.servlet.http 
packages. These packages are standard J ava extensions avail able from 
J avaSoft for J DK 1.1 and built-in toj DK 1.2. The request/response model is 
used by general Web browser and server interactions over the I nternet, and 
it applies to servlet behavior as well. Because HTTP is a stateless protocol, 
one request/response knows nothing about another request/response, even 
from the same Web browser, unless additional session state features are 
added. 


WebSphere Installation 

The WebSphere Application Server Version 2.02 was used to run the sample 
code provided in this book. 

One thing to consider prior to installation is to make sure you are using a 
specific IP address instead of an I P address provided through a DHCP server 
(we did experience problems with a DHCP address). 
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The installation process for WebSphere Application Server is fairly simple. 
The only thing you need to know is the Web server that is used with 
WebSphere. It is a good idea to install the Web server prior to installing 
WebSphere. Also make sure you select the right Web server to work with 
WebSphere, because there is no easy way to change this after the 
installation. 


WebSphere Configuration 

To configure different components of WebSphere you use the administration 
applet of WebSphere. Togain access on your browser input thefollowing 
U RL : http: / /<server-name>:9527 or http: / !<ip-address>:9527 . This Starts the 
applet and displays the main administrator login panel (Figure 1). 



ibm WebSphere 

ll>j)li(<tlion Sort er 2.0 

Advanced Edition 


IBM WebSphere Application Server Administration Log In 






If you have just installed, type "admin" for user and password 


Figure 1. WebSphere Administrator L ogin Panel 


From the administration panel you configure different components of 
WebSphere (Figure 2). 
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Figure 2. WebSphere Administration Panel 

Servlet and Java Class Files Location 

The servlet and J ava class files should reside under: 

<drive>:\WebSphere\AppServer\servlets\<package name (if any)> or 
<dri ve>: \WebSphere\AppServer\classes\<package-name>. 

Keep in mind that the classes placed under theserv/ets directory can be 
replaced at any time without the need to restart WebSphere. On the other 
hand, the cl asses placed under the classes directory do require WebSphere to 
be restarted when they are replaced. Therefore, the classes directory is the 
proper place to store any packages that will most likely not change, whilethe 
servlets directory is the best place during development and testing. 

Servlets are addressed with the U RL: 

http://<server-name>/servl et/packagename.Cl assName 


WebSphere Configuration for JDBC 

To run a servlet with J DBC in WebSphere, we have to makethej DBC 
drivers available. See "Configuring WebSphere for J DBC"on page49for 
detailed instructions. 
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Starting and Stopping WebSphere 

When using the I BM HTTP server it is not necessary to start WebSphere 
explicitly. This is done automatically when the HTTP Server is started. 

To stop WebSphere use the Control Panel ->Services (Figure 3) and stop the 
WebSphere Servlet Service. Next, stop th el BM HTTP Server. To restart, just 
start the IBM HTTP Server again and verify that the WebSphere Servlet 
Service is started as well. 



Figure 3. Services Panel : Starting and Stopping WebSphere 
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2 V sualAge for Java 
Enterprise Version 2 

Because Visual Age for J ava Version 2contains some very nice tools to 
develop, debug, and run servlets and EnterpriseJ avaBeans in a test 
environment, Visual Age for J ava was used to develop the samples. 

I n this chapter we briefly describe how to install and configure VisualAge for 
J ava to work properly with the I BM WebSphereTest Environment. 
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VisualAge for Java Installation 

The installation consists of three steps: 

1. Install VisualAge for J a va version 2.0 GA release, reboot, start Visual Age 
for J ava, and exit. 

2. Install fixpack Rollup2 by unzipping the f\\e rol I up2_vaj20_wi n.zi p to the 
VisualAge for J ava directory ( c:\iBMVAJava ), start VisualAge for J ava to 
complete the installation, and exit. 

3. I nstall the Enterprise U pdate, start VisualAge for J ava, and exit. 

During the installation VisualAge for J ava asks for the directory for 
HTM L files; thedefault path is <drive>:\wm\html. This is the location 
wherethe/B/W WebSphere Test En viron merit looks for the HTM L files. 


VisualAge for Java Configuration for JDBC 

To run J ava programs with J DBC in Visual Age for J ava, we have to make the 
JDBC drivers available. See "Configuring VisualAge for J ava for J DBC" on 
page 48 for detailed instructions. 


VisualAge for Java Configuration for WebSphere 

Once the installation is complete, you should add th e/BM WebSphereTest 
Environment feature to the Workbench by selecting Workbench ->File-> 
Quick Start (Figure 4). 



Figure 4. Add Feature to VisualAge for J ava E nvironment 
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Select Feature->Add Feature and select IBM WebSphereTest Environment 
1.1 (Figure 5). 


[^Selection Required 


Select the features to add to the workspace. 


IBM Common Persistence 2.1 

IBM Data Access Beans 1.0 

IBM Domino Examples 2.0 

IBM EJB Development Environment 1.1 

IBM Enterprise Access Builder Library 2.0 

IBM Enterprise DCS Access Builder Library 1.0 

IBM Enterprise CPP Access Builder Examples 2.0 

IBM Enterprise CPP Access Builder Library 2.0.1 

IBM Enterprise Data Access Examples 2.0 

IBM Enterprise Data Access Libraries 2.0.1 NL 

IBM Enterprise RMI Access Builder 2.0.1 

IBM Enterprise Toolkit for AS/400 2.0 

IBM ET_Workstation Examples 1.0 

IBM Java Examples 2.0 

IBM Java Record Library 2.0 

IBM JSP Execution Monitor 1.1 

IBM Servlet Builder 2.1 

IBM Servlet Builder Examples 2.1 

IBM Servlet IDE Utility class libraries 2.0.3 


IBM WebSphere T e$t Environment 1.1 


flDL Development Environment 2.0 
| IDL Development Environment Examples 2.0 

| OK | Cancel | 

k 


Figure 5. Feature Selection Panel 

If the feature has already been added it will not be listed. Adding the feature 
will allow you to run servlets within the Visual Age for J ava environment. 


WebSphere in VisualAge for Java 

I n this section we describe the necessary steps involved in setting up and 
running servlets inside VisualAge for J ava. 

Default Directories for Servlets and JSP files 

The HTM L and J SP files should reside under: 

<dri ve>: \www\html (refer to "VisualAge for J ava I nstallation" on page 10) 

TheXML servlet configuration files (.servlet) should resideunder: 

<drive>: \IBMVJova\ide\project_resources\<project name>\<[package name]> 
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Compiled JSPs 

When thej SP file is accessed through a servlet it is translated into a J ava 
file and its class is executed in the Visual Age for J ava environment. Thej ava 
version of thej SP filecan be found in they SP PageCompileGenerated Code 
project in the Visual Age for J ava Workbench. 


Running Servlets in VisualAge for Java 

There are a couple of steps you have to take to run your Websphere 
application. F rom the Workbench select the com. ibm. servlet package in the 
IBM WebS phereTest E nvironment project. E xecute the SE Runner class to 
start the servlet runtime environment. Depending on the processing power of 
your machine this will take between 20 to 120 seconds to get started. 

Before running SERunner makesurethe project in which the servlet code is 
residing is included in the cl ass path of SERunner (F igure 6). 

One safe option is to select all the projects and add them to the cl ass path of 
the SERunner class. 

To run J SPs, they SP PageCompileGenerated Code project must also be 
added to the cl ass path. This project does not exist originally; it is created 
when the first J SP is compiled. Only then can the project be added to the 
class path of the SERunner class. 
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& Workbench [Administrator] 

File Edit Workspace Selected Window Help 

*j V ®) £) ®) 

\\i- 5 * Projects^! 

All Projects 


-Ini 


i Packages f0 Classes jO Inte ^ Plopel(ies , OI SERi 


*1 


!±l £3 com. ibm. oats, connection 1.1 
-■ £3 com. ibm. oats, jdbc 1.1 
-Big com. ibm. oats, utils 1.1 
-■ & com. ibm. servlet 1.1 
33 Q PageListS 1.1 
S3© PageListServlet^ 1.1 
B © PageNotFoundException^ 1.1 

a ETTO BiBsnn 

a © SERunnerSSERunnerFrameS) 1.' 
a © SEVersionS1 1.1 

com. ibm. servlet, classloader 1 .1 
-ffl £3 com. ibm. servlet, cmdline 1.1 

com. ibm. servlet, commlinks 1 .1 
ffl £3 com. ibm. servlet, config 1.1 

com. ibm. servlet, config. directory 1 . 1 
-B £3 com.ibm.servletconfiguration 1.1 
aS com. ibm. servlet, connmgr 1.1 
a m com. ibm. servlet, controller 1.1 
a m com. ibm. servlet, controller, config 1.1 
-a £3 com.ibm.servlet.controller.message 1.' 
-B £3 com. ibm. servlet, debug 1.1 
BfS com. ibm. servlet, directory 1.1 
-a £3 com.ibm.servlet.ejs 1.1 
aS com. ibm. servlet, engine 1.1 
a® com. ibm. servlet, engine, api 1.1 
a m nnm ihm servlet ennine iws 1 1 


f Program [ Class PathJ Info] 

[7 Include (dot) in class path 


0 Project path: 

Compute Now | 

|IBM Data Access Beans;! BM Java Implementation;! B 

Edit... 


(7 Extra directories path: 


Class Path 


Select the projects to include on the class path. 


Eh 


0IBM Data Access Beans 
0IBM Java Implementation 
□ IBM JSP Examples 
0 IBM JSP Execution Monitor 
0IBM Servlet IDE Utility class libraries 
0 IBM WebSphere Test Environment 


ITSO SG24 5471 


□ ITSO Test 

0Java class libraries 

0JFC class libraries 

0JSP Page Compile Generated Code 

0 Sun class libraries PM Win32 




u 

1 0 selected 




Select all 


Deselect all 


OK 


Cancel 


d 


J 




© Source (cannot be modified) 


com. ibm. servlet. S E R unner 1 . 1 (Administrator) 


Figure6. ClassPath Setup for the WebSphereTest Environment 


When the WebSphere test environment is up and running you can launch 
your servlets by selecting the servlet class and Tools ->Servlet Launcher -> 
Launch from the context menu. If the SE Runner is not running, this process 
will launch the SERunner. After SERunner is launched, a series of messages 
is displayed in the Console window of Visual Age for J ava. At some point a 
message "Server Process: Server started" gets logged. Despite what the 
message indicates, the server does some further processing before it is fully 
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operational. Figure7 shows the final message in the Console window that 
indicate the server is truly up and running. 


Checking if server is already started on port: 8080 
***Starting WebSphere Test Environment*** 
ServerProcess : Start services 
ServiceManager: Load service adminservice 


Servlet reloading is disabled 
ServiceManager: Autostarting servl etservi ce 
ServiceManager: Autostarting httpservice 
ServerProcess: Server started. 


servl etservi ce: Load (update): 

endpoi nt .mai n . port =80 
Servi ceParameters : 
servletservice: Load (update): 
endpoi nt .mai n . port =80 


Figure 7 . SampleConsoleOutput from SE Runner 
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ITSO Sample 
Applications 


The sample code developed for this book is available as a Zl P file on the 
I nternet: 

ftp : //www. redbooks . i bm . com/redbooks/SG24547 1/ 

The5471samp.zipfileexpands intoa directory structure containing all the 
sample code: 

\WasDbBk\Code <=== sample files for book chapters 

\WasDbBk\Code\Repository <=== VisualAge for Java export files (.dat) 
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Sample Code 


Table 1 describes the sample code subdirectory structure and the files 
contained in those subdirectories. 

Table 1. Directories and Files with SampleCode 


Subdirectory 

Files 

Description 

Main directory: \ WasDbBk\ Code 

DBase 

xxx.ddl 

Database definition DDL for DB2, 

Oracle, and SQL Server 

xxx. icx, XXX. CSV 

Sample table data load files 

Repository 

xxx. dat 

VisualAge for J ava repository export 
file 

itso\ wasdb\ ..pkg 

xxx. cl ass, xxx.java 

VisualAge for J ava exported classes, 
matching the package structure 

deployableEJ Bs 

xxx.jar 

VisualAge for J ava jar files for 
deployment of EJ Bs to WebSphere 

Html 

xxx.html 

HTML, J SP, and servlet XML files 

Studio 

xxx. war 

WebSphere Studio archive file 

xxx.java, .html, 

.jsp, .servlet, .sql 

WebSphere Studio generated files 
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Repository Export Files 

The repository subdirectory ( \WasDbBk\code\Repository ) contains one file: 
5426samp.dat (contains project ITSO SG24 5471) 

Table 2 describes the samples that we developed and the repository packages 
where the code is stored. 

Table2. Models and Packages in the Repository Samples 


Package 

Descripti on 

itso.wasdb.jdbc 

J DBC example and servlet example 

itso.wasdb.connmgr 

Connection manager example 

itso.wasdb.accessbean 

Data access bean example 

itso.wasdb.connaccess 

Data access bean with connection manager 

itso.wasdb. persist, metadata 

Persistence Builder model, schema, map 

itso.wasdb. persist 

Persistence Builder domain classes 

itso.wasdb. persist. Services 

Persistence Builder service classes 

i tso.wasd b.persi st.gui 

Persistence Builder GUI application 

itso.wasdb.ejb 

EnterpriseJ avaBeans 

itso.wasdb.ejb.client 

EnterpriseJ avaBeans client example 

itso.wasdb.ejb.servlet 

EnterpriseJ avaBeans servlet example 

itso.wasdb.studio 

WebSphere Studio example 

itso.wasdb.userprofile 

WebSphere user profile example 

itso.wasdb.sqlj 

DB2 SQLJ example 

ITSO_EJ BsEJ BReserved 

EnterpriseJ avaBeans control information 


To load the packages into the repository, use the import function of VisualAge 
forj ava. You can import the whole projects or just individual packages. After 
importing you have to load the packages into the Workbench, either into your 
own project or by using the ITSO SG24 5471 project. 
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Part 2 Database Setup 

and JDBC 


I n this part we discuss the installation and setup required for all of the 
relational database products and the setup required to create a J DBC 
connection to your database. 

I n our project we used three different relational database management 
systems, together with the WebSphere Application Server, WebSphere 
Studio, and Visual Age for J ava 

□ DB2 UDB Version 5.2 

□ Oracle 8i, Version 8.0.4 

□ Microsoft SQL Server, version 7.0 
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4 Relational Database 
Installation and 
Setup 

I n this chapter we describe the installation and setup of the relational 
database products used for the examples throughout this book. For the 
purpose of the samples provided, all of the databases do share the same name 
and tableformats. Because the scripts used to create these databases were 
slightly different, all three scripts are posted here. 

To standardize the data structures accessed in each of the database products, 
we created a simplesampledatabasecalled/TSCM/l/DB to run queries 
against. We created a schema under the ID ITSO. Therefore all of thetable 
names used arelTSO.<TABLENAM E>. Thesampledata definition language 
(DDL) or SQL filefor every database is listed under the corresponding 
installation section. 
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DB2 UDB Installation 


We installed DB2 Universal Database for Windows NT Version 5,2. To keep 
the version current, UDB fixpack WR09074, also known as fixpack 6, was 
installed. 

TousetheSQLJ functionality, you must install fixpack 8 (seeChapter 14, 
"Using SQLJ to Access a Database” on page 247). 


DB2 UDB Database Setup 

After DB2 is installed, you need to create the ITSOWDB database. You can 
either use a GUI with the DB2 Control Center or use a DB2 command 
wi ndow. 

If you are using the Control Center, you select Systems -> [ComputerN ame] -> 
Instances ->DB2 -> Databases. Open the context menu (right click) and 
select Create->New (Figure 8). 



Figure8. Creating a New Databaseusing theControl Center 

A SmartGuide prompts you for the database name (Figure 9). For the 
purpose of our sample code, you do not have to use the other pages of the 
SmartGuide dialog. Enter the name and click on Done. 
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Figure 9. Create Database SmartGuide 

If you are using a DB2 Command Window run the command: 

db2 create database itsowdb 

If you want to find out more about the create database options, enter: 

db2 ? create database 

This command lists all of the options availablefor the particular DB2 
command. 

User ID 

By convention we create all tables under the ITSO user I D (with the 
password itso). Because of this you need to add the/TSO user I D to the 
database user list. M ake sure that the user I D ITSO is already created in the 
WindowsNT operating system. 

The simplest way to to add the user I D to the database is through the Control 
Center. Select the ITSOWDB database and open User and Group Objects. I n 
the context menu (right mouse click) select DB Users and select Add. From 
the Add User panel select the ITSO user ID and give it all of the Authorities. 
Then click on Apply and then on Close (Figure 10). 


Chapter 4. Relational Database Installation and Setup 23 




Figure 10. Add User to a Database 


DB2 UDB Table Creation 

When the database is created, the next step is to create the tables in the 
database. Figure 11 shows the itsowdb.ddl file file used to create the tables. 
To execute this file, open a DB2 Command Window and run the command: 

db2 -tvf itsowdb.ddl 

Use the proper directory (c: \WasDbBk\dbase\db2) for the script file. 

Two tables are created: 

□ Department 

□ Employee 

These tables definitions are similar to the tables of the DB2SAMPLE 
database. We decided not to use the SAM PLE database, so that we can have 
the same database and tables i n al I three database systems. 
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CONNECT TO itsowdb; 

DROP TABLE ITSO. EMPLOYEE; 

DROP TABLE ITSO. DEPARTMENT; 

DDL Statements for table ITSO. DEPARTMENT 

CREATE TABLE ITSO . DEPARTMENT ( 

DEPTNO CHAR(3) NOT NULL , 

DEPTNAME VARCHAR(29) NOT NULL , 

MGRNO CHAR(6) , 

ADMRDEPT CHAR(3) NOT NULL , 

LOCATION CHAR(16) ); 


ALTER TABLE ITSO. DEPARTMENT 

ADD PRIMARY KEY (DEPTNO); 

DDL Statements for table ITSO. EMPLOYEE 

CREATE TABLE ITSOWDB. ITSO. EMPLOYEE ( 

EMPNO CHAR(6) NOT NULL , 

FIRSTNME VARCHAR ( 12) NOT NULL , 

MIDINIT CHAR(l) NOT NULL , 

LASTNAME VARCHAR(15) NOT NULL , 

WORKDEPT CHAR (3) , 

PHONENO CHAR (4) , 

HIREDATE DATE , 

JOB CHAR(8) , 

EDLEVEL SMALLINT NOT NULL , 

SEX CHAR ( 1 ) , 

BIRTHDATE DATE , 

SALARY DEC IMAL ( 9,2) , 

BONUS DECIMAL(9,2) , 

COMM DEC IMAL (9,2) ); 


ALTER TABLE ITSO. EMPLOYEE 

ADD PRIMARY KEY (EMPNO); 

DDL Statement for foreign key relationship 

ALTER TABLE ITSO. EMPLOYEE ADD FOREIGN KEY (WORKDEPT) 

REFERENCES ITSO. DEPARTMENT (DEPTNO) ON DELETE RESTRICT; 

Load sample data 

LOAD FROM DEPARTMENT. CSV OF DEL INSERT INTO ITSO. DEPARTMENT; 
LOAD FROM EMPLOYEE. CSV OF DEL INSERT INTO ITSO. EMPLOYEE; 
SET CONSTRAINTS FOR ITSO. EMPLOYEE IMMEDIATE CHECKED; 

CONNECT RESET; 

Figure 11. DB2TabieCreation 
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Loading the Table Data Into DB2 

The load statements at the bottom of Figure 11 load the sample data into the 
tables from a data filethat uses one line of comma-delimited data for each 
row of the tables. 

An extract of the sample data (.csv files) is shown in Figure 12. 


Department, csv 

"A00" , "SPIFFY COMPUTER SERVICE DIV "000010" , "A00" , "SAN JOSE" 

"B01", "PLANNING", "000020", "A00", "SAN JOSE" 

"C01", "INFORMATION CENTER" , "000030" , "A00" , "SAN JOSE" 

"D01", "DEVELOPMENT CENTER" ,, "A00" , "SAN JOSE" 

"Dll", "MANUFACTURING SYSTEMS" , "000060" , "D01" , "SAN JOSE" 

"D21", "ADMINISTRATION SYSTEMS" , "000070" , " DO 1 " , "SAN JOSE" 

"E01", "SUPPORT SERVICES", "000050", "A00", "SAN JOSE" 

"Ell", "OPERATIONS", "000090", "E01", "SAN JOSE" 

"E21", "SOFTWARE SUPPORT" , "000100" ," E01 " , "SAN JOSE" 

Employee. csv 

"000010", "CHRISTINE", " I", "HAAS", "A00", "3978", " 1965-01-01 PRES", 18, "F"," 1933-08-24", 

0052750.00, 0001000.00, 0004220.00 

"000020", "MICHAEL", " L", "THOMPSON", "B01 ","3476", "1973- 10- 10", "MANAGER", 18, "M"," 1948-02 
-02", 0041250.00, 0000800.00, 0003300.00 

"000030", "SALLY", "A", "KWAN" , "C01" , "4738", "1975-04-05", "MANAGER" ,20, "F" , "1941-05-11", 

0038250.00, 0000800.00, 0003060.00 

"000050", "JOHN", "B", "GEYER", "E01 ","6789", "1949-08- 17 "."MANAGER", 16, "M"," 1925-09-15", 

0040175.00, 0000800.00, 0003214.00 

"000060", " IRVING", "F” , "STERN" , "Dll" , "6423" ," 1973-09-14" , "MANAGER" , 16, "M" , " 1945-07-07" 

, 0032250.00, 0000500.00, 0002580.00 

"000070", "EVA", "D"," PULASKI", "D21", "7831 ","1980-09-30", "MANAGER", 16, "F"," 1953-05-26", 

0036170.00, 0000700.00, 0002893.00 

"000090", "El LEEN", "W", "HENDERSON", " Ell ","5498", "1970-08- 15", "MANAGER", 16, "F"," 1941-05 
-15", 0029750.00, 0000600.00, 0002380.00 

"000100" , "THEODORE" , "Q" , "SPENSER" , " E21 " , "0972" , "1980-06-19" , "MANAGER" , 14, "M" ," 1956-12 
-18", 0026150.00, 0000500.00, 0002092.00 

"0001 10" , "VINCENZO" , "G" , "LUCCHESSI " , "A00" , "3490" , " 1958-05-16" , "SALESREP" , 19 , "M" , "1929 
-11-05", 0046500.00, 0000900.00, 0003720.00 

"000120", "SEAN"," ", "0 1 CONNELL", "A00", "2167"," 1963- 12-05", "CLERK", 14, "M"," 1942-10- 18", 

0029250.00, 0000600.00, 0002340.00 

"000130", "DOLORES", "M", "QUINTANA", "C01", "4578", " 1971-07-28", "ANALYST", 16, "F"," 1925-09 
-15", 0023800.00, 0000500.00, 0001904.00 

"000140", "HEATHER", "A", "NICHOLLS", "C01", "1793", "1976- 12- 15", "ANALYST", 18, "F"," 1946-01 
-19", 0028420.00, 0000600.00, 0002274.00 

"000150", "BRUCE"," ", "ADAMSON" , "Dll" , "4510" , "1972-02-02" , "DESIGNER" , 16, "M" , 
"1947-05-17", 0025280.00, 0000500.00, 0002022.00 


Figure 12. DB2 Sample Data Extract 


DB2 JDBC Drivers 

The DB2 J DBC drivers are in thee: \SQLLiB\java\db2java.zip file. This file 
must be availabletoj ava through the cl ass path. 
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Oracle 8 Installation 

We have installed a standard developer installation of Oracle Version 8.0.4 
under Windows NT. 

Notice 

I n our installation the Oracle installer did not copy thej DBC driver files. 
Make sure those driver files are installed if you plan to access an Oracle 
database using J DBC. We copied thedriver files manually from the 
installation CD from win32/v8/Jdbc to c:\orant\jdbc, which was the home of 
our Oracle8 installation. 

Moreover, if you later want to use the OC I Driver (see "Oracle OCI Driver" 
on page 46) you either have to put c; \orant\jdbc\lib in the system path or 
place the oci804jdbc.dll somewhere in the path, for example, 

c: \WinNT\system32. 


Oracle Database Setup 

We assume that Oracle is installed. We are now going to create the tables of 
the itsowdb database, and fill the tables with sampledata. 

User ID 

By convention, all tables arecreated under th elTSO user I D, sothefirst 
thing to do is to create the ITSO user. To do that, open the Oracle 8 
Navigator. I n the tree go all the way down to the User node (Figure 13). 

I n the General Pane create the user ITSO with password /tso; in the 
Privileges Pane give the new ITSO user additionally the Resource Role 
(Figure 14). 
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Figure 13. Creating a /Vew User for Oracle 



Figure 14. Assigninga Roletoan OracleUser 
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Oracle Table Creation 


Now that the user is created, the next step is to create the database tables. 
You will notice that we have not yet created a database ourselves. During the 
installation of Oracle, a database is created that holds all the tables. 

Figure 15 lists the SQL statements used to create the ITSOWDB tables. 


CONNECT itso/itso; 


DROP TABLE ITSO. EMPLOYEE; 

DROP TABLE ITSO. DEPARTMENT; 


DDL Statements for table ITSO. DEPARTMENT 

CREATE TABLE ITSO. 

DEPARTMENT ( 

DEPTNO 

CHAR(3) NOT NULL , 

DEPTNAME 

VARCHAR(29) NOT NULL , 

MGRNO 

CHAR(6) , 

ADMRDEPT 

CHAR(3) NOT NULL , 

LOCATION 

CHAR ( 16) ); 

ALTER TABLE ITSO. DEPARTMENT 

ADD PRIMARY KEY (DEPTNO); 


DDL Statements for table ITSO. EMPLOYEE 

CREATE TABLE ITSO. 

EMPLOYEE ( 

EMPNO 

CHAR(6) NOT NULL , 

FIRSTNME 

VARCHAR ( 12) NOT NULL , 

MIDINIT 

CHAR(l) NOT NULL , 

LASTNAME 

VARCHAR( 15) NOT NULL , 

WORKDEPT 

CHAR(3) , 

PHONENO 

CHAR (4) , 

HIREDATE 

DATE , 

JOB 

CHAR(8) , 

EDLEVEL 

SMALLINT NOT NULL , 

SEX 

CHAR(l) , 

BIRTHDATE 

DATE , 

SALARY 

DEC IMAL ( 9,2) , 

BONUS 

DEC IMAL (9,2) , 

COMM 

DEC IMAL (9,2) ); 

ALTER TABLE ITSO. EMPLOYEE 

ADD PRIMARY KEY (EMPNO); 


DDL Statement for foreign key relationship 

ALTER TABLE EMPLOYEE ADD FOREIGN KEY (WORKDEPT) 

REFERENCES 

I DEPARTMENT (DEPTNO); 

COMMIT; 



Figure 15. OradeTableCreadon 
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To create the tables, start the SQL PI us 8.0 tool from the Start menu. 
Connect as user ITSO with password itso. You will useth e itsowdb.ddl file 
from the Oracle directory. From the SQL> prompt, issue the command: 

start c:\WasDbBk\dbase\Oracl e\ itsowdb.ddl 

Use the correct path for the SQL file for your installation. Figure 16 displays 
the result when you issue the start command to execute the SQL. 



Figure 16. OradeTableCreadon Output 

Now your tables are set up to import the actual data. To do that, use the 
OraddB Navigator again. Expand the tree until you seethe new tables in the 
local databases. You should have at least one table named DEPARTMENT 
and one named EMPLOYEE. Because the default installation of Oracle8 
installs tables with the same names, make sure you import the data to the 
correct tables. Verify this by inspecting that owner of the tables is ITSO. 
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Importing the Table Data into Oracle 

I import the data by selecting I mport From File (Figure 17). Then specify the 
data file, which is either empl oyeecsv for the employee table or 
department csv for the department table. Both files reside in the same 
directory as the itSOWdb.ddl file (c:\WasDbBk\dbase\Oracle). 



Figure 17. I mport Data For TheEmployeeTable 

Thesampledata files are almost identical to the files used for DB2. An 
extract of thesampledata is shown in Figure 18. 

The format of the date columns is different, oi-jan- 1965 instead of 1965-01-01. 
To distinguish results of queries, we use employee numbers starting with the 
number 1, that is, 100010 instead of ooooio. 
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Department, csv 

"AOO" , "SPIFFY COMPUTER SERVICE DIV 100010" , "AOO" , "SAN JOSE" 

"B01", "PLANNING"," 100020", "AOO", "SAN JOSE" 

"C01", "INFORMATION CENTER" , "100030" , "AOO" , "SAN JOSE" 

"D01", "DEVELOPMENT CENTER" ,, "AOO" , "SAN JOSE" 

"Dll", "MANUFACTURING SYSTEMS" 100060" , "D01 " , "SAN JOSE" 

"D21", "ADMINISTRATION SYSTEMS" 100070" , "D01 " , "SAN JOSE" 

"E01", "SUPPORT SERVICES", "100050", "AOO", "SAN JOSE" 

"Ell", "OPERATIONS", "100090", "E01", "SAN JOSE" 

"E21", "SOFTWARE SUPPORT" ," 100100" ," E01 " , "SAN JOSE" 

Empl oyee.csv 

" 100010", "CHRISTINE", "I", "HAAS", "AOO", "3978", "01- JAN- 1965", "PRES", 18, "F" , "24-AUG- 1933 
", 0052750.00, 0001000.00, 0004220.00 

" 100020", "MICHAEL", "L", "THOMPSON", "B01 ", "3476", " 10-0CT-1973" , "MANAGER", 18, "M","02-FEB 
-1948", 0041250.00, 0000800.00, 0003300.00 

"100030", "SALLY", "A", "KWAN" , "C01" , "4738", "05-APR- 1975", "MANAGER" ,20, "F" ," ll-MAY-1941" 
, 0038250.00, 0000800.00, 0003060.00 

" 100050", "JOHN", "B","GEYER","E01 ","6789", " 17-AUG- 1949", "MANAGER", 16, "M" , " 15-SEP-1925" 
, 0040175.00, 0000800.00, 0003214.00 

" 100060", " IRVING", "F", "STERN", "Dll", "6423", " 14-SEP-1973" , "MANAGER", 16, "M","07-JUL- 194 
5", 0032250.00, 0000500.00, 0002580.00 

" 100070", "EVA", "D", " PULASKI", "D21", "7831 ","30-SEP- 1980", "MANAGER", 16, "F", "26-MAY- 1953 
", 0036170.00, 0000700.00, 0002893.00 

" 100090", "EILEEN","W","HENDERS0N","E11","5498","15-AUG-1970","MANAGER",16,"F"," 15-MAY 
-1941", 0029750.00, 0000600.00, 0002380.00 

" 100100", "THEODORE", "Q", "SPENSER", "E21", "0972", "19-JUN- 1980", "MANAGER", 14, "M\" 18-DEC 
-1956", 0026150.00, 0000500.00, 0002092.00 

"1001 10", "VINCENZO", "GV'LUCCHESSI", "AOO", "3490", " 16-MAY-1958" , "SALESREP" , 19, "M", "05- 
NOV-1929" , 0046500.00, 0000900.00, 0003720.00 

" 100120" , "SEAN" , " ", "0 1 CONNELL" , "AOO" , "2167" , "05-DEC- 1963" , "CLERK" , 14, "M" , 
"18-0CT-1942", 0029250.00, 0000600.00, 0002340.00 

"100130", "DOLORES", "M", "QUINTANA", "C01", "4578", "28-JUL- 1971 "."ANALYST", 16, "F","15-SEP 
-1925", 0023800.00, 0000500.00, 0001904.00 

" 100140", "HEATHER", "A", "NICHOLLS", "C01", "1793", "15-DEC- 1976", "ANALYST", 18, "F","19-JAN 
-1946", 0028420.00, 0000600.00, 0002274.00 

"100150", "BRUCE"," ", "ADAMS0N","D1 1", "4510", "12-FEB- 1972", "DESIGNER", 16, "M", 
"17-MAY-1947", 0025280.00, 0000500.00, 0002022.00 


F i gure 18. Or ac ! e S ampl eData E xtract 

The database is now ready. You may verify this by selecting one of the tables 
(right click) and open it. 


Oracle JDBC Drivers 

The Oracle J DBC drivers are in the c:\orant\jdbc\lib\classeslll. zip file. This 
filemust be avail able to J ava through theclass path. 
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SQL Server Installation 


We installed SQL Server Version 7.0 Desktop. Before you proceed with the 
installation you should gototh el nstallation Pre-requisite sect ion. Check and 
make surethe I nternet E xpl orer version you haveisequal or greater than the 
version mentioned in the pre-requisite. If you have an older version, proceed 
with the prerequisite installation and then goand install the SQL server. 


SQL Server Database Setup 

There are a few steps you must follow to enable access to SQL Server through 
WebSphere. Because SQL Server does not provide a J DBC driver, we use the 
SunJ DBC/ODBC bridge to get a connection to the database. 

Create ITSOWDB Database 

The first step is to create our database: 

□ Open the SQL Server Enterprise Manager. 

□ Expand ConsoleRoot -> M icrosoft SQL Server ->SQL Server Group -> 
[Computer-Name] -> Databases and select New Database from the context 
menu (Figure 19). 



Figure 19. Createa N&v Database 
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□ Now enter the database name ITSOWDB in the Name: entry field and 
click OK. 

Setup User ID as Owner 

To create the database tables with the ITSO schema you have to add the 
ITSO user ID into the list of Logi ns as follows: 

□ From Enterprise Manager expand ConsdeRoot ->M icrosoft SQL Server -> 
SQL Server Group -> [Computer-N ame] and open Security. 

□ Right mouse click on Logins and select New Login. 

□ I nput ITSO as the N ame and select your Domain under Authentication. 

□ Under Defaults for Database select ITSOWDB. 

□ Select Server R oles tab and check System Administrators. 

□ Select Database Access, check ITSOWDB and check public and db_owner 
as database roles. Now click on the OK button. 


SQL Server Table Creation 

To create the tables for SQL Server we run the DDL commands in the 
c:\WasDbBk\dbase\SQLServer\itsowdb.ddl file. To run this fileyou haveto run the 
Query Analyzer. This is a separate SQL Server tool found from Windows 
Start ->P rograms -> SQL Server, or from the SQL Server Enterprise manager 
select Tools ->SQL Query Analyzer. Open thefileand run it (Figure 20). 

Make sure to select thelTSOWDB database from the list of databases on the 
top menu bar. 
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DROP TABLE ITSO. EMPLOYEE; 

DROP TABLE ITSO. DEPARTMENT; 

DDL Statements for table ITSO. DEPARTMENT 

CREATE TABLE ITSO . DEPARTMENT ( 

DEPTNO CHAR (3) NOT NULL , 

DEPTNAME VARCHAR(29) NOT NULL , 

MGRNO CHAR(6) , 

ADMRDEPT CHAR(3) NOT NULL , 

LOCATION CHAR ( 16) ); 


ALTER TABLE ITSO. DEPARTMENT 
ADD PRIMARY KEY (DEPTNO); 

DDL Statements for table ITSO. EMPLOYEE 

CREATE TABLE ITSOWDB . ITSO. EMPLOYEE ( 


EMPNO 

CHAR(6) NOT NULL , 

FIRSTNME 

VARCH AR ( 12) NOT NULL 

MIDINIT 

CHAR(l) NOT NULL , 

LASTNAME 

VARCHAR ( 15) NOT NULL 

WORKDEPT 

CHAR(3) , 

PHONENO 

CHAR(4) , 

HIREDATE 

DATETIME , 

JOB 

CHAR(8) , 

EDLEVEL 

SMALLINT NOT NULL , 

SEX 

CHAR(l) , 

BIRTHDATE 

DATETIME , 

SALARY 

DEC IMAL (9,2) , 

BONUS 

DEC IMAL ( 9,2) , 

COMM 

DECIMAL(9,2) ); 


ALTER TABLE ITSO. EMPLOYEE 
ADD PRIMARY KEY (EMPNO) ; 


DDL Statement for foreign key relationship 

ALTER TABLE ITSO. EMPLOYEE ADD FOREIGN KEY (WORKDEPT) 
REFERENCES ITSO. DEPARTMENT (DEPTNO); 


Figure 20. SQL Server TabieCreation 


Importing the Table Data into SQL Server 

We now have to fill our tables with content. The easiest way to do this is to 
use the import/export wizard. From the Microsoft SQL Server 7.0 program 
group start / mport and Export Data. Skip the entry panel with the 
introduction text and proceed to the second panel. 


Chapter 4. Relational Database Installation and Setup 35 




□ Make sure you select T&d Fileas the source. Then specify the path 
(c: \WasDbBk\dbase\SQLServer) where the csv files are located (Figure 21). 



Figure 21. Import Data for Department Table 

□ I n the next panel you may specify the file format of the text file that is to 
be imported. It should not be necessary to make any changes. 

□ Then you may specify the column separator. Again the default should be 
sufficient. 

□ Figure 22 shows the next step. Be sure to select the correct database as 
the import destination. 
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Figure 22. Choosea Destination 

□ Now the destination table has to be specified. I n this case we import the 
department data into the department table as destination (Figure 23). 


Select Source Tables 

You can choose one or more tables to copy. You can copy the schema and data as it is in 
the source or click (...) to transform the data using ActiveX scripts. 


lable(s): 


Source T able 

M 

H:\WasdbBk\CODEV. 




[itsowdb], [dbo], [department] 



T ransform 



Figure 23. Select the Destination Table 

□ I n the next step you may specify additional options, for example, if this 
import process should be stored. We skip this step and click Next. 

□ The wizard shows its last panel, informing us that the import process is 
now specified and ready to run. Click Finish. If everything runs fine, SQL 
Server will inform you with a message box (Figure 24). 
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T lansferring Data 



Flat File Microsoft SQL Server 

Progress: 

llllllllllllllllllllllllllllllllllll 


Jransfer status: 



Step Name 

Status 

0 

Create Table [itsowdb], [dbo], [department] Step 

Complete 

0 

Copy Data from department to [itsowdb], [dbo], [department] ... 

Complete (9) 



Figure 24. I mporting Data Was Successful 


The same import has to be performed for the employee table using the 
empl oyee csv file. 

Thesampledata files are identical to the files used for Oracle (Figure 18 on 
page 32), with the exception that we used employee numbers starting with 
the number 2, that is, 200010 instead of 100010. 


SQL Server JDBC Drivers 

SQL Server does not providej DBC drivers. We use the J DBC/ODBC bridge 
drivers provided by Sun in thej DK. To use the bridge we have to set up an 
ODBC data source. 


ODBC Data Source Setup for JDBC 

Toenablethe ITSOWDB database for ODBC orforthej DBC/ODBC bridge, 
you have to set up an ODBC data source: 

□ Go to the Control Panel and open ODBC Data Sources. 

□ I n the ODBC Data Source Administrator select th eSystem DSN tab 
(Figure 25). 
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f 'l ODBC Data Source Administrator 


User DSN System DSN | File DSN | Drivers] Tracing] Connection Pooling | About | 


System Data Sources: 


Add., 


| Name 

Driver 

1 Locals erver 

SQL Server 

MQIS 

SQL Server 


Remove 


Configure.. 


An ODBC System data source stores information about how to connect to 
the indicated data provider. A System data source is visible to all users 
on this machine, including NT services. 




Figure 25. ODBC Data SourceAdministrator 
□ Select Add to add a new DSN (Figure 26). 



Figure 26. Create New Data Source 
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□ Select SQLServer and click on Finish. 

□ Enter the name, description, and server for the Data Source Name, then 
click Next (Figure 27). 



Figure 27. Create New Data Source to SQL Server 

□ Now specify what kind of authorization you want the database to use and 
then click on Next. 

□ Next you select the I TSOWDB database for the ODBC connection. Click 
on Next (Figure 28). 
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Create a New Data Source to SQL Server 



17 Change the default database to: 



3 


r Attach database filename: 

I 



(7 Use ANSI quoted identifiers. 

17 Use ANSI nulls, paddings and warnings. 

r- Use the failover SQL Server if the primarjr SQL Server is not 
available 


< Back | Next > | Cancel | Help 


Figure 28. Create New Data Source to SQL Server (Database Setup) 

□ On th eODBC Microsoft SQL Server Setup Panel click on Test Data Source 
toconfirmthat your selections werecorrect and that the connection can be 
established. Then click on Finish. 


Note 

You must make sure to set up a System DSN and not a User DSN. If you 
set up a User DSN you will not be able to establish a connection to SQL 
server through WebSphere, because it is using a default system I D to gain 
access. 
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5 Java Database 
Connectivity 

Sun developed thej ava Database Connectivity (J DBC) data access layer to 
keep thej ava API for accessing relational databases standard across all 
vendors. Similar to M icrosoft's ODBC, this layer providesj ava programmers 
a generic way to communicate with relational databases regardless of the 
database vendor. 

Most vendors provide J DBC drivers for their products, which enables you to 
access the vendor's database using thej DBC API. For more detailed 
information on J DBC drivers and categories of drivers, refer to the IBM 
redbook Application Development with Visual Age for J ava E nterprise, 
SG24-5081. 


©Copyright IBM Corp. 1999 
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DB2 UDB JDBC Drivers 


IBM provides twoj DBC drivers for standard access to DB2. Each was 
developed by utilizing previously written software, so each implements the 
connection differently. The drivers are shipped with DB2UDB and are 
located in the file: 

c:\SQLLIB\java\db2java.zip 

When testing your J DBC applications, this file must be accessible in thej ava 
class path, or your application will not be abletofind thej DBC drivers. 


DB2 Application Driver 

The DB2 application driver is in the COM ./ bm.db2.jdbc.app.DB2Driver 
class, located in the db2java.zip class collection file. This driver uses 
the URL format of 

jdbc:db2:<database name> (jdbc:db2:itsowdb) 

Known as a category (or type) 2J DBC driver, this driver takes advantage of a 
previously written database client software. It contains aj DBC bridge that 
cl oses the gap between thenewj ava coded driver and the legacy client access 
software. The bridge takes J DBC commands and translates them into the 
traditional commands used in the client software. In DB2's case, the DB2 
Client Application Enabler (CAE) is used (Figure 29). Thej DBC drivers 
must have CAE code libraries available to access the server. 



CLIENT SERVER 

Figure 29. Category 2 J DBC Driver, Vendor Specific Bridge 

When thej DBC bridge accesses CAE code, the client is accessing non-J ava 
code libraries. This driver is not used for communication between client and 
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server across a network because of its use of platform dependent code. This is 
because you cannot package the non-J ava, platform specific code, into a JAR 
file to send to a client when the client requests direct access to an 
independent database server. 


DB2 Network Driver 

The network driver is in th eCOM .ibm.db2.jdbcnet.DB2Driver class, also 
located in thedb2java.zip class collection. It has a U RL of the format: 

jdbc:db2://<hostname>:<port>/<database> (jdbc:db2: / /sonoma: 6789/it sowdb) 

This driver is known as a category 3J DBC driver, which splits thedriver 
code between the client and the server. The client contains the purej ava 
code and the server contai ns the platform specific code. When a database cal I 
is issued, the client translates the cal I into a generic network protocol. The 
server then translates the cal I back into a J DBC call and processes the cal I on 
the server. Because the client is purej ava, this is a good implementation for 
network use (Figure 30). 



Figure 30. Category 3 J DBC Driver, Generic Network Protocol 

These drivers require software on the server, also known as middleware, to 
fulfill the database request and return the result tothe client; for DB2 this is 
the DB2 J DBC applet server. You must start this service on the server from 
the San//' ces menu in the Control Panel, it uses the default port number of 
6789. You can also start it from a DOS command prompt by issuing the 
command: 

db2jstrt <port number> (db2jstrt 6789) 
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Oracle JDBC Drivers 

Oracle provides two categories of J DBC, a thin client driver which is pure 
J ava and a second driver known as the Oracle Call I nterface (OCI ) driver. 
TheOCI driver is not purej ava and uses platform-specific native methods to 
access the database. 

Both drivers are implemented in the oracl ej d bcdri ver.Orad eD ri ver class. 


Oracle Thin Client Driver 

The thin client driver is a type4 client driver which requires only sockets to 
connect toan Oracle database. Thedriver is completely implemented in J ava, 
so it is platform neutral and does not require any Oracle software to be 
installed on the client. 

A type4, according to the definition of J avaSoft, is a native-protocol fully 
J ava technology-enabled driver. 

The U RL to access a database through the thin client is: 

jdbc: oracl e:thin:@<servername>:<portriumber>:<databasename> 

I n our examples we use the default database instance ore/ and the default 
port number 1521, therefore the resulting URL is: 

j dbc : oracl e : thi it :@local host: 1521: Orel 

Oracle OCI Driver 

The OCI driver is a type 2 driver. By definition a category 2, or type 2, driver 
is a native-API partlyj ava technology-enabled driver (as shown in Figure 29 
on page 44). It provides an implementation of thej DBC based on the native 
OCI to access the database. 

Since native methods are used to interact with the database, the OCI driver 
is platform specific. Although this driver is not suitable for applets, the OCI 
driver has the advantage of better performance. This makes it ideal for being 
used by servlets on the server. As we tested, both drivers work with 
WebSphere, provided that the Application Server class path includes the 
Oracle drivers, and that for the OCI driver the oci804jdbc.dl I file is in the 
system path (see "Oracle 8 I nstallation"on page 27). 
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The U RL to access a database using the OCI driver is somewhat longer: 

jdbc:oracl e:oci8:@(description=(address=(host=<servername>) 

(protocol=tcp) (port=<portrumber>) ) (connect_data= (sid=<databasename>))) 

In our examples we use the default database instance ore/ and the default 
port number 1521, therefore the resulting URL is: 

jdbc:oracle:oci8:@(description=(address=(host=l ocal host) 

(protocol =tcp) (port=1521) ) (conrect_data=(si d=orcl ) ) ) 


SQL Server JDBC Drivers 

M icrosoft does not provide a J DBC driver for SQL Server. J avaSoft does 
packageaj DBC/ODBC bridge in the sun.jdbcodbcj dbcOdbcDriver class. It 
uses a U RL format of jdbc:odbc:<ODBC Data Source Name>. Sun's driver does have 
a few shortcomings; it is a type 2 driver, which means it cannot be used in 
applets. Also it can only connect to local ODBC Data Source Names. 

An ODBC Data Source is a system defined way for a driver to connect to an 
ODBC compliant data provider. To use ODBC drivers (or a J DBC/ODBC 
bridge), you must define an ODBC Data Source Name (DSN) for the data 
provider (for example, SQL Server) sothat your driver knows how to retrieve 
information from the data provider. In Windows, you can define an ODBC 
Data Source Name (DSN) by using the ODBC Data Source Administrator, 
located in the Windows Control Panel. It is possible to define a DSN on your 
machine for a remote server, but access must be granted on the server for 
your specific machine name. 

M any vendors offer drivers which can connect directly to remote servers, but 
most require some middleware totransl ate the callsfromj DBC toODBC. A 
company named i-net software (www.inetsoftware.de) does offers a category 4 
driver for SQL Server. This driver has made a positive impression on the 
J ava community, but we have neither tested nor implemented this product. A 
category 4 driver is a purej ava driver that connects directly to the server 
and does not require any ODBC setup or use. Category 4 drivers are the most 
preferred drivers. 
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Configuring VisualAge for Java for JDBC 

To use the databases from within the development environment of VisualAge 
for J ava, the drivers have to be made visible in Visual Age for J ava. There are 
two ways to achieve this. 

The first possibility is to include the zip files containing thej DBC drivers in 
the cl ass path of VisualAge for J ava: 

□ The DB2 zip file is c:\sqlli b\java\db2java.zip 

□ The Oracle zip file is c:\orant\Jdbc\1ib\classeslll.zip 

□ Thej DBC/ODBC bridge for SQL Server is part of the standard SunJ ava 
cl asses. 

To add the zip files to the cl ass path, open the Options dialog from the 
Window menu in VisualAge for J ava. Click on Resources on the left side and 
edit the Workspace cl ass path on the right side, as in Figure 31. 



Figure31. Editing VisualAge for J ava's Class Path 
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The second possibility is to import the zip files into the repository and 
Workbench of Visual Age for J ava. This has the advantage that, if later on an 
application or an applet is packed together with the required J DBC drivers, 
VisualAgefor J ava will be ableto include the drivers in the resulting J AR 
files. 

To import the zip file use the import feature. Select File->lmport and select 
J ar-file as input source, browse for thejar file (either db2java.zip or 
dasseslll.zip) and import it, for example under the new project Database 
J DBC Drivers. 


Configuring WebSphere for JDBC 

To use the DB2 and OracleJ DBC drivers for servlets within WebSphere it is 
necessary to include the driver classes in the WebSphere class path. Open a 
Web browser with theWebSphereadministration page (http ://<server-name or 
ip-address>:9527), goto Setup ->] ava Engine, and add 

c:\sqllib\java\db2java.zip (DB2) 

c:\orant\Jdbc\lib\classeslll.zip (Oracle) 

to the Application Server Classpath Entry (Figure 32). 


D Introduction 

^0 Setup 

0 Administration 
0 Connection Manageme 
0 Directory Management 
0 Java Engine 
0 Session Tracking 
0 User Profile 
0 Virtual Hosts 

► 0 Servlets 

► 0 Enterprise Java Services 

► 0 Security 

► 0 Server Execution Analysis 
0 Log Off 



<3 Ready 


Use this page to specify basic Java Virtual Machine (JVM) settings and whether to run the Application Server as par 
the Web server, or in stand alone mode. 


Save | 

Revert | 

Defaults | 


Paths | Memory | Directives | Process 

Use System Classpath? C Yes <• No 

Application Server Classpath: |...; c:\sqllib\j a va\db2java.zip;c:\orant\Jdbc\lib\classes1 1 1 .zip;. 
Reloadable Servlet Classpath: | 

Java Path: | C:\JDK11~1.7B\bin 
Java Libpath: | C:\JDK1 1 ~1 ,7B\bin 
User Libpath: | C:\WEBSPH~1tAPPSER~1\plugins\nt 


Figure 32. J DBC Drivers in WebSphere Cl ass Path 
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Part 3 Database 

Programming 

Examples 


This part describes all of the code implementations of integrating Websphere, 
VisualAgefor J ava, and database managers. These examples are simplified 
to facilitate your understanding of the concepts. After reviewing these 
examples you should have developed the basic knowledge necessary to 
integrate Websphere J ava servlets and database management systems in 
more complex environments. 

For all of the development and tests that are not automated by WebSphere 
Studio, we used I BM 's VisualAgefor J ava. We recommend the use of this 
development suite for its power, ease of use, and its tight integration with 
WebSphere. This tight integration provides seamless portability of your code 
between the two products. 


©Copyright IBM Corp. 1999 
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6 JDBC Programming 
Examples 

This chapter briefly describes, through examples, the basics of connecting 
J ava applications and servlets to databases using J DBC. These examples 
should merely be used as building blocks and to understand the concepts. 


Simple JDBC Application 

We implemented a simple class to handle the common interaction with each 
vendor's databases. This class, shown in Figure 33, was implemented using 
Visual Age for J ava and created under the itso.wasdb.jdbc package. 

The program logic uses the following methods: 

□ makeConnectiorr. creates a connection to the database, prints a message 
tothe console saying the connection was successful, and then returns the 
connection tothecaller. 
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package itso.wasdb.jdbc; 

import java.sql 

public class SimpleSQL { 

// Instance variable for the URL property 
private String url = null; 

// Instance variable for the userlD property 
private String userlD = null; 

// Instance variable for the password property 
private String password = null; 

// Instance variable for Connection 
private Connection con = null; 

public void makeConnecti on () { 
try { 

con = DriverManager.getConnection(url , userlD, password); 
System. out. pri ntl n ("Connected to Database; " + url+"\n"); 
} catch (SQLException se) { 

System. out. print(se) ; 

} catch (Exception e) { 

System. out. pri ntl n (e) ; 

} 

return; 


public void setPassword(String aPassword) { 
password = aPassword; 

} 

public void setURL(String aUrl) { 
url m aUrl ; 

} 

public void setUserID(String aUserlD) { 
userlD = aUserlD; 

} 


public void executeSQL() throws SQLException { 
Statement stmt = con.createStatement() ; 


ResultSet rs = stmt.executeQuery("Sel ect empno, lastname, deptname, mgrno 
from i tso.empl oyee A, itso. department B where A.workdept = B.deptno"); 


System. out. pri ntl n ("EMPNO LASTNAME DEPT 

while (rs.next()) { 

String si = rs.getString("EMPNO") ; 

String s2 = rs.getString("LASTNAME") .concat(" 
String s3 = rs.getString("DEPTNAME") .concat(" 
String s4 = rs.getString("MGRNO") ; 

System. out. pri ntl n(sl + " " + s2 + " " + s3 + 


MGRN0\n") ; 


) .substri ng (0, 14) ; 

") .substring(0,29) ; 


+ s4) ; } 


Figure 33. SimpleClass for J DBC Access 
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□ setXXX: methods to set the database connection parameters. 

□ etecuteSQL: executes an SQL statement and displays the result set to the 
console. This SQL statement performs an inner join of the two tables 
based on the employee’s department. It displays the employee number, 
last name, work department, and the department manager's employee 
number, as shown in the output (Figure 34). 

Note that for this simplified example, weare not catching all possible 
exceptions. 


Connected to Database: 

jdbc :db2: i tsowdb 


EMPNO 

LASTNAME 

DEPT 

MGRNO 

000010 

HAAS 

SPIFFY COMPUTER SERVICE DIV. 

000010 

000120 

O'CONNELL 

SPIFFY COMPUTER SERVICE DIV. 

000010 

000110 

LUCCHESSI 

SPIFFY COMPUTER SERVICE DIV. 

000010 

000020 

THOMPSON 

PLANNING 

000020 

000030 

KWAN 

INFORMATION CENTER 

000030 

000140 

NICH0LLS 

INFORMATION CENTER 

000030 

000130 

QUINTANA 

INFORMATION CENTER 

000030 

000060 

STERN 

MANUFACTURING SYSTEMS 

000060 

000220 

LUTZ 

MANUFACTURING SYSTEMS 

000060 

000210 

JONES 

MANUFACTURING SYSTEMS 

000060 

000200 

BROWN 

MANUFACTURING SYSTEMS 

000060 

000190 

WALKER 

MANUFACTURING SYSTEMS 

000060 

000180 

SC0UTTEN 

MANUFACTURING SYSTEMS 

000060 

000170 

Y0SHIMURA 

MANUFACTURING SYSTEMS 

000060 

000160 

PIANKA 

MANUFACTURING SYSTEMS 

000060 

000150 

ADAMSON 

MANUFACTURING SYSTEMS 

000060 

000070 

PULASKI 

ADMINISTRATION SYSTEMS 

000070 

000270 

PEREZ 

ADMINISTRATION SYSTEMS 

000070 

000260 

JOHNSON 

ADMINISTRATION SYSTEMS 

000070 

000250 

SMITH 

ADMINISTRATION SYSTEMS 

000070 

000240 

MARINO 

ADMINISTRATION SYSTEMS 

000070 

000230 

JEFFERSON 

ADMINISTRATION SYSTEMS 

000070 

000050 

GEYER 

SUPPORT SERVICES 

000050 

000090 

HENDERSON 

OPERATIONS 

000090 

000310 

SETRIGHT 

OPERATIONS 

000090 

000300 

SMITH 

OPERATIONS 

000090 

000290 

PARKER 

OPERATIONS 

000090 

000280 

SCHNEIDER 

OPERATIONS 

000090 

000100 

SPENSER 

SOFTWARE SUPPORT 

000100 

000340 

G0UN0T 

SOFTWARE SUPPORT 

000100 

000330 

LEE 

SOFTWARE SUPPORT 

000100 

000320 

MEHTA 

SOFTWARE SUPPORT 

000100 


Figure 34. J DBC ExampleOutput 
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DB2 Universal Database JDBC Code Example 

We use both the application driver ( com.ibm.db2.jdbc.app.DB2Driver ) and 
the network driver ( com.ibm.db2.jdbc.net.DB2Driver ) in Figure 35 to 
illustrate the coding of each driver. 

For the network driver, you must remember to start thej DBC applet server 
on the server machine. This network driver uses a generic network protocol 
to send its request to the server, then platform specific code on the server 
translates the call to the database manager. See "DB2 Network Driver” on 
page 45 for further details. 

The port specified in the network driver’s URL must correspond to the port 
defined when the middleware on the server (DB2J DBC applet server) is 
started. 


package itso.wasdb.jdbc; 
public class Db2SQL { 

public static void main(java. 1 ang.Stri ng [] args) { 

SimpleSQL udbSQL = new Simpl eSQL ( ) ; 

SimpleSQL udbSQLnet = new Simpl eSQL ( ) ; 

String drv = "C0M.ibm.db2.jdbc.app.DB2Driver"; 

String drvnet = "C0M.ibm.db2.jdbc.net.DB2Driver"; 

try { 

Cl ass .forName(drv) ,newlnstance() ; 
udbSQL. setUserID("itso") ; 
udbSQL. setPassword("itso") ; 
udbSQL. setURL(" jdbc: db2: itsowdb") ; 
udbSQL. makeConnectionQ ; 
udbSQL. executeSQL() ; 

// You must start the JDBC Applet Server on the server machine with port 2222. 
// Issue db2jstrt 2222 from command prompt 
Cl ass .forName( drvnet) .newlnstance() ; 
udbSQLnet. setUserID("itso") ; 
udbSQLnet .set Password ("i tso") ; 

udbSQLnet.s etURL(" jdbc :db2: //SONOMA: 2222/ itsowdb") ; 
udbSQLnet. makeConnectionQ ; 
udbSQLnet. executeSQL() ; 

} catch (Exception e) { 

System.out.pri ntl n (e) ; 

} 


Figure 35. DB2 UDB J DBC CodeExample 
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Oracle JDBC Code Example 

The Oracle example is straightforward and differs only in the usage of the 

drivers. We used both OracleJ DBC drivers (Figure 36). 

We assume a standard installation of Oracle with the default settings: 

□ The Oracle server is located on the same machine where the example is 
running. If Oracle is running on another machine, localhost must be 
replaced by the name of the appropriate machine. 

□ The database instance is the default instance which is created during 
installation of Oracle, namely ore/. If other database instances are used, 
this is to be replaced by the appropriate names. 

□ The default port number 1521 is used for the Oracle server listener. This 
can be changed in the O rad eNet8 Assistant tool. 


package itso.wasdb.jdbc; 

public class OracleSQL { 

public static void main(String args[]) { 

SimpleSQL orclThinSql = new Simpl eSQL ( ) ; 

SimpleSQL orclOciSql - new Simpl eSQL ( ) ; 

String drv = "oracl e.jdbc.dri ver. Oracl eDriver" ; 

String urlThin = "jdbctoracl e:thi n:@l ocal host : 1521 :orcl" ; 

String urlOci = "jdbctoracl e:oci8:@(descri pti on=(address= (host=l ocal host) 
(protocol =tcp) (port =1521) ) (connect_data=(si d=orcl )) ) " ; 

try { 

Cl ass .forName(drv) ,newlnstance() ; 

// First try the thin driver 
orclThinSql .setUserID("itso") ; 
orclThinSql .setPassword("itso") ; 
orclThinSql .setURL(urlThin) ; 
orclThinSql .makeConnecti on () ; 
orclThinSql .executeSQL() ; 

// Now try the OCI driver 
orclOciSql .setUserID("itso") ; 
orclOciSql .setPassword("itso") ; 
orclOciSql . setURL(url Oci ) ; 
orclOciSql .makeConnecti on() ; 
orclOciSql .executeSQLQ ; 

} catch (Exception e) { System. out. pri ntl n(e) ; } 

} 

} 


F i gure 36. Oracl ej DBC C ode E xampl e 
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SQL Server JDBC Code Example 

We decided to use Sun's J DBC/ODBC bridge driver for our example. It 
provides limited functionality but is sufficient for our testing. When using a 
J DBC/ODBC Bridge, it is important tocreatean ODBC Data Source Name 
(DSN) for your data server. In Windows NT, go to the Control Panel and 
select ODBC Data Sources. 

Because we are using Sun's driver, we must use a user DSN to access our 
database. I n the Data Sources panel, select the Add button to add a DSN for 
SQL Server. A prompt for the data source will appear, and if SQL Server is 
installed, it will be listed as a possible source. You must specify a name, 
description, and a server. You can enter a remote server by entering the 
remote server computer name. This is the only way to connect to a remote 
server if you are using Sun's driver. The next screen will prompt you on how 
to check the authority of a login ID. For remote server authentication you 
should select SQL Server for authorization as in Figure 37. You should also 
add this I D to the SQL Server running on the remote computer. 



Figure 37. ODBC DSN Authorization 

The rest of thesetup is self-explanatory; we chose the default settings for all 
other panels. When you are done, you should have a new Data Source Name, 
In Figure 38 we have already added a local and remote SQL Server. 
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Figure 38. ODBC Data SourceAdministrator 

F igure 39 contai ns the cl ass we used to connect to SQL Server. We i nstanti ate 
the driver and then set our parameters. Notice that our U RL uses the 
J DBC/ODBC bridge standard naming convention: 

jdbc:odbc:<server name>:<Data Source Name> 


package itso.wasdb.jdbc; 
public class SqlSrvSQL { 

public static void main(java.lang.String[] args) { 
SimpleSQL sqlsrvsql = new Simpl eSQL ( ) ; 

String drv = "sun. jdbc.odbc.JdbcOdbcDriver" ; 
try { 

Cl ass .forName(drv) ,newlnstance() ; 
sqlsrvsql ,setUserID("itso") ; 
sql srvsql ,s et Password ("i tso") ; 
sqlsrvsql ,setURL("jdbc:odbc: SQLSERVER") ; 
sqlsrvsql .makeConnecti on () ; 
sql srvsql ,executeSQL() ; 

} catch (Exception e) { System. out. pri ntl n(e) ; } 

} 

} 


Figure 39. SQL Server J DBC ExampleCode 
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Running Applications with JDBC 

ThesampleJ DBC applications can be tested in VisualAgefor J ava, and they 
can be run outside of VisualAgefor J ava in the operating system. 


Testing the JDBC Applications in VisualAge for Java 

Toexecutethesampleapplications in VisualAgefor J ava, make sure that the 
J DBC drivers are in the class path. See "Configuring VisualAgefor J ava for 
J DBC” on page 48 for detailed instructions. 

Select thej ava class of the application and click on th e Run icon in the tool 
bar. You can also select Run ->Run main from the context menu. The output 
of the application is displayed in the VisualAgefor J ava Console window. 

Note: TheOracleOCI driver does not work in VisualAgefor J ava. It seems 
that the required DLL cannot be loaded. 


Running the JDBC Applications in the Operating System 

A J ava J DK must be installed in the operating system. To run the sample 
applications, export the cl asses from VisualAgefor J ava into a directory that 
is in thej ava class path of the operati ng system. 

We exported theclasses into the c:\WosDbBk\code directory. This operation 
creates subdirectories matching the package name of theclasses, that is, 
c : \ klasDbBk \ code \itso\ wasdb \jdbc. 


Class Path for Java Applications 

The class path must includethej DBC drivers and theexported code. We 
changed the operating system CLASSPATH environment variablefrom the 
Control Panel -> System icon to include: 

c:\sql 1 ib\java\db2java.zip 

c:\orant\jdbc\lib\classeslll.zip 

c:\WasDbBk\code 


Run the JDBC Application 

To execute thej DBC applications, open a command window and enter: 

java itso.wasdb.jdbc.Db2SQL 
java itso.wasdb.jdbc.OracleSQL 
java itso.wasdb.jdbc.SqlSrvSQL 
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Simple JDBC Servlet 

We implemented a simplej DBC servlet to gain experience with the 
WebSphereTest Environment of Visual Age for J ava and with deployment of 
the code to the WebSphere Appl ication Server. 

Our servlet consists of two classes: 

□ DbServletBean: a bean that contains all thej DBC code to list the 
employees of the employee table. 

□ DbServlet: a servlet that accepts a parameter to select the database 
management system and then calls the bean toexecutethej DBC code. 

The servlet (DbServlet) contains a doGet method that is called from the Web 
server's servlet engine (Figure 40). 

The servlet sets up the bean with thej DBC driver, U RL, user I D, and 
password, before calling the execute method to run thej DBC code. A 
parameter named database is passed to the servlet to select the database 
management system (DB2, Oracle, or SQLServer). 

Thej DBC bean (DbServletBean) contains the following methods: 

□ setURL: to set the value of the database URL 

□ setUserlD: to set the user I D for the connection 

□ setPassword: to set the password for the connection 

□ makeConnection: to connect to the database using the U RL, user I D, and 
password 

□ executeSQL : to execute the select statement: 

select empno, lastname, deptname, mgrno 
from itso. employee A, itso. department B 
where A.workdept = B.deptno 

□ output! nfo: to create the HTM L table with the result of the select 

We do not show the code of thej DBC bean here because it is very similar to 
the simplej DBC application. The only difference is that the output is routed 
back to the Web server instead of being written to the console. 
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public class DbServlet extends HttpServlet { 

public void doGet (HttpServl etRequest req, HttpServl etResponse res){ 

String drv = " ", url = " 

String database = req. getParameterVal ues ("database") [0] ; 
if (database. equal s("DB2") ) { 

drv = "COM. i bm.db2. jdbc.app ,DB2Dri ver" ; 
url = "jdbc: db2 : i tsowdb" ; 

} 

else if (database. equal s ("Oracl e") ) { 

drv = "oracl e. jdbc. driver. Oracl eDri ver" ; 
url = "jdbc : oracl e:thin:@l ocal host : 1521: ore 1 " ; 

} 

else if (database. equal s ("SQLServer") ) { 
drv = "sun. jdbc. odbc.JdbcOdbcDriver"; 
url = "jdbc: odbc:SQLSERVER" ; 

} 

PrintWriter out = null; 

DbServl etBean dbBean = new DbServl etBean () ; 
try { 

out = res.getWriter() ; 
out.println("<HTML><BODY>") ; 

Cl ass .forName(drv) ,newlnstance() ; 
dbBean. setUserID("itso") ; 
dbBean. setPassword("itso") ; 
dbBean. setURL(url ) ; 

out.println("<hl> Attempting to Connect </ h l><p> " ) ; 

out.println("URL: "+ url + "<br>Driver: "+drv) ; 
dbBean. makeConnection() ; 

out.println("<hl> Connection was successful </h l><p> " ) ; 

dbBean. executeSQL(out) ; 

} 

catch(SQLException sqlExcept) { 

out.println("<hl> EXCEPTION IN SAMPLE CODE </hl><p>"); 

out .printl n ("Error : " + sql Except. getErrorCode() ) ; 
out .printl n ("State: " + sql Except. getSQLState() ) ; 
sql Except. printStackTrace(out) ; 

} 

catch (Exception except) { 

out.println("<hl> EXCEPTION IN SAMPLE CODE </hl><p>" ) ; 

out. print In (except) ; 
except. printStackTrace(out) ; 

} 

out.println("<HTML><BODY>") ; 


} 


Figure 40. S imple Servlet doGet M drhod 
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Testing the Servlet in VisualAge for Java 

Start the WebSphere Test Environment (review "Running Servlets in 
VisualAge for J ava”on page 12). 

To run the servlet you open a Netscape browser and enter the URL: 

h ttp: //local host: 8080/servlet/it so. wasdb. jdbc.DbServl et?database=DB2 
h ttp: //local host: 8080/servlet/it so. wasdb. jdbc.DbServl et?database=Oracle 
http: //local host: 8080/servlet/it so. wasdb. jdbc.DbServl et?database=SQLServer 

Alternatively you can set up the servlet database parameter through the 
servlet launcher properties dialog in VisualAge for J ava (select the servlet 
cl ass and Tool s-> Servlet Launcher -> Properties). Enter the parameter name 
(database) and the value (DB2, Oracle, or SQLServer). Then launch the 
servlet by selecting Tools ->Servlet Launcher ->Launch. This starts a Web 
browser with the correct U RL. 

Theoutput of theservlet is shown in Figure41. 


Running the Servlet in WebSphere 

To deploy the servlet to WebSphere export the classes to the WebSphere 
servlets directory (c:\WebSphere\AppServer\servlets). 

Makesurethat thej DBC drivers are in the WebSphere cl ass path (review 
'WebSphere Configuration forj DBC" on page 7). 

Open a Web browser and enter the U RL: 

http ://<hostname>/servlet/it so. wasdb. jdbc.DbServl et?database=DB2 
http ://<hostname>/servl et/ it so. wasdb. jdbc.DbServl et?database=Oracl e 
http ://<hostname>/servlet/it so. wasdb. jdbc.DbServl et?database=SQLServer 

Theoutput of theservlet is shown in Figure41. 
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Figure 41. SimpleServlet Output in a Web Browser 
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7 IBM Connection 
Manager 

The introductory text in this chapter is reprinted from the December 1998 
issue of the IBM De/eloper Connection Technical Magazine. 

The connection manager provides the means to manage pool (s) of connections 
to one or moredatabase(s). It classes are made of wrapper classes around the 
cl asses over java. sql classes. Having these wrapper classes, J DBC 
connections are passed to applications requesting connection. 

The goal of the connection manager is to reduce the percentage of resources 
used by the nonproductive con nect/di scon nect overhead, so that these 
resources are available to handle more traffic. The connection manager also 
provides a way to allocate relational database resources so that during peak 
request volumes the more critical servlets have greater access to the 
database resources than less critical servlets. 

Performance and scalability are two of the most advantages of the connection 
manager. A servlet needing a connection toa relational database will get an 
existing connection from the pool, through theconnection manager, rather 
than having to create a new connection on its own. This is the key to the 
connection manager's role: connections are kept open and are reused, so the 
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connect/disconnect overhead is spread over many, entirely separate user 
requests coming in over the I nternet. WebSphere makes the connection pool 
management scalable by allowing the connection pool parameters to be 
modified dynamically. Figure42 shows the interaction between the 
connection manager and a servlet. 



/ \ 



Figure42. Interaction Flow Between theConnection Manager and a Servlet 

Servlets which are using theconnection manager can run inside VisualAge 
forj ava using the WebSphere Test Environment or outside using WebSphere 
itself. 
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Configuration 

The connection pools are configurable through the WebSphere Application 
Server Administrator panel (Figure43). For information on how to get to the 
Administrator panel please refer to "WebSphere Configuration" on page 6. 


WebSphere Application Server 


D Introduction 
▼O Setup 

0 Administration 
0 Connection Management 

0 Directory Management 
0 Java Engine 
0 Session Tracking 
0 User Profile 
0 Virtual Hosts 

► O Servlets 

► O Enterprise Java Services 

► O Security 

► O Server Execution Analysis 
0 Log Off 


Connection Management 


Ready 


Pool Types I Pool List 


Pool 


Type 


J 


^ JdbcDb2 
^ JdbcOracle 
^ Jdbclnformix 
^ JdbcSqlserver 
^ JdbcSybase 


JDBC 

JDBC 

JDBC 

JDBC 

JDBC 


J 








Add 

Edit 

Remove 






Figure43. Connection Management on WebSphere 


Connection Pool 

There is a set of pre-defined connection pools provided as default for database 
servers such as: 

□ IBM DB2 

□ Oracle 

□ Informix 

□ Microsoft SQL Server 

□ Sybase 

You can customize your pool by adding a new one to the list or edit an 
existing one (Figure 44). 

It is also possible to add multi pie entries differing in the pool name for 
different databases of the same vendor. This is even more likely. For example, 
one could add a pool entry specifying that the data base(s) addressed by this 
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pool have longer lasting time out than other databases, addressed by other 
pool entries, because the user interaction in a transaction is longer. 


WebSphere Application Server 


D Introduction 
▼O Setup 

0 Administration 
0 Connection Management 

0 Directory Management 
0 Java Engine 
0 Session Tracking 
0 User Profile 
0 Virtual Hosts 

► O Servlets 

► O Enterprise Java Services 

► O Security 

► O Server Execution Analysis 
0 Log Off 


Connection Management 

♦ sonoma 


&C3 Ready 


hj:B Connection Management 

-=JSl-Xj|| 


10 


Pool Type: JDBC 
Pool Name: 
Maximum Connections: 
Minimum Connections: 
Connection Time Out: 
Maximum Age: 
Maximum Idle Time: 


200000 


-1 


-1 


Reap Time: T 


OK 


Warning: Applet Window 


Cancel 


Figure 44. Connection Pool Configuration 

These are the parameters that can be set for the connection pool : 

Pool Type: The type of data server used by this pool of connections. J DBC 
indicates aj DBC-compliant database. A data server is a product that helps 
you manage and access data. Usually, it is a relational DBMS such as DB2, 
Oracle, I nformix, or Sybase. 

Pool Name: The unique name for this pool of connections. Servlet 
programmers need to know this name for their servlets to use this connection 
pool. 

Maximum Connections: M aximum number of connections that can be in 
the pool. Consider setting it to the maximum number of users permitted by 
your DBMS product license agreement. 

Minimum Connections: The minimum number of connections that can 
remain in the pool as a result of the reap process. The connection manager 
periodically removes connections that become idle or orphaned. Usethis 
setting to keep from removing too many connections, erasing resource usage 
performance gains. 

Connection TimeOut: The length of time (in milliseconds) the connection 
manager will wait for a connection to become free when all connections in the 
pool are currently in use and the number of connections has reached the 
maximum (meaning no new connections can be created to fulfill the need). 
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□ A value of 0 allows the connection manager to wait forever. 

□ A value of -1 disables the wait (an exception is immediately thrown if a 
connection is not available). 

□ A val ue of 1000 to 2000 (1 to 2 seconds) is suggested. 

□ Servlet programmers must know the value of the connection time out to 
effectively set the waitRetry parameter in their servlets. 

Maximum Age: The maximum number of seconds a connection can be idle 

before the reap process releases the connection from the servlet that owns it. 

□ A valueof -1 disables this function; the reap process will not releaseany 
connections from idle servlets. 

□ A valueof 900 to 1800 (15 to 30 minutes) is suggested. 

Maximum IdleTime: The maximum number of seconds an unassigned 

connection can remain in the pool. 

□ A valueof -1 disables this function; the reap process will not remove any 
connection from the pool and disconnect it from the data server. 

□ A valueof 900 to 1800 (15 to 30 minutes) is suggested. 

Reap Time: The interval (in seconds) at which the connection manager 

performs the reap process. 

□ A valueof -1 disables this function; the reap will not be performed, 
regardless of the values specified in Maximum Age or Maximum IdleTime 
parameters. 

□ A valueof 1800 to 3600 (30 to 60 minutes) is suggested. 


IBM Connection Manager and Pure JDBC 

When using standard J DBC for database connection, you are responsible for 
creating a new connecting to the database and then closing it. Once the 
connection is closed, the next transaction will have to create a new 
connection to access the database. 

When using the I BM connection manager you get a connection from a 
connection pool. If a connection is availablethe connection manager will 
return a IBMJ dbcConnection from which you can obtain its underlying 
J DBC connection. When you are done using the connection, you do not close 
the connection; you merely release it. This way it can be used by the next 
party requesting a connection to a database. The connection obtained 
through connection manager should not be closed, that is, do not call 
Conn action, close 
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IBM Connection Manager Examples 

I n our programming examples we have made connections through the 
connection manager using servlets, A select query is run against the 
empl oyee table and the result is displayed on a page using HTML. The 
connections have been made to three different databases: 

□ IBM DB2 

□ Oracle 

□ SQL Server 

Every database example has its own class. All of the classes related to the 
connection manager example are part of th eitso.wasdb.connmgr package. 
The example for all three databases performs the same task. As a result, all 
three classes do inherit their common function from a super class. The super 
cl ass name i s DbaseConnMgr. 

When describing the code, only the segments that are relevant to the 
connection manager usage are described. The rest is left to the reader’s 
ability to read the code and understand its purpose. 


Using the IBM Connection Manager 

The package in which the connection manager classes reside is 
/ bm.servl et. conn mgr. 

There are several steps you must follow to use the connection manager. 

□ Create a connection specification using IBMJ dbcConnSpec. 

□ Get a reference to the connection manager object using the static method 
IBM Con nM grU til.getl BMConnMgr. 

□ Get an I BMJ dbcConn object, that is, a wrapper around a J DBC 
connection, using the connection manager's getl BM Connection method. 

□ Get a java. sql. Connection Object using getj dbcConnection of the class 
IBMJ dbcConn. 

Now you have a connection to the database for your transactions. 

Once you aredone with the transaction, you have to release the connection to 
be returned into the pool. You do this by calling the rd easel BM Connection 
method of the / BMJ dbcConnection class. 
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Notice 


Keep in mind that the connections provided through the connection 
manager are subject to time-outs, depending on the maximum age 
parameter. If the difference in the time when you have obtained the 
connection and the time when you are going to use it is rather long, 
compare it to maximum age. It is recommended to use 
veri fyl BM Connection prior to using the connection. If the servlet still owns 
the connection, the method returns true. Otherwise false will be returned 
and you have to obtain a new connection object. 


HTML File for Accessing the Servlets 

A simple HTM L file is used to provide access to launch the servlets through 
WebSphere (Figure 45). You have to use this file only when you are trying to 
launch the servlets outside of Visual Age for J ava. 


<! DOCTYPE HTML PUBLIC "-//SQ//DTD HTML 2.0 + all extensi ons//EN" "hmpro3.dtd"> 

<HTML> 

<HEAD> <TITLE> JDBCServlet </TITLE> </HEAD> 

<B0DY BGC0L0R= "#FFFFFF"> 

<P> 

<table width=580 border=0 cel 1 paddi ng=20> 

<tr> 

<td valign=top> 

<H2><center>IBM Connection Manager</center></H2> 

<P>The following provides an access to three different databases using 
IBM Connection Manager . 

</td> 

</tr> 

<tr> 

<td val i gn=bottom> 

What would you like to do? 

<br><br>&nbsp;&nbsp; 

<A HREF="/servl et/itso.wasdb.connmgr.UdbConnMgr" TARGET="_bl ank">Run IBM DB2 UDB 
Sampl e</A> 

<br>&nbsp;&nbsp; 

<A HREF="/servl et/itso.wasdb.connmgr.Sql SrvConnMgr" TARGET="_bl ank">Run MS SqlServer 
Sampl e</A> 

<br>&nbsp;&nbsp; 

<A HREF="/servl et/i tso.wasdb.connmgr.Orcl ConnMgr" TARGET="_bl ank">Run Oracle 
Sampl e</A> 

<br>&nbsp;&nbsp; 

</td> 

</tr></tabl e> 

</B0DY> 

</HTML> 


Figure45. HTML for theConnection M anager Servlet Examples 
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Running the Example 

There are two ways in which you can run this sample: 

1. Using the WebSphere Test Environment in Visual Age for J ava 

Select the servlet class, for example itso.wasdb.connmgr.U dbConnM gr, 
and launch it from the context menu using Tools -> Servlet Launcher -> 
Launch (Figure 46). 


m mmrnmm r 

3 itso.wasdb.ejb 1 .7 
3 itso.wasdb.ejb. di 
3 itso.wasdb.ejb.se 
3 itso.wasdb.jdbcA 
3 itso.wasdb.persis 
3 itso.wasdb.persis 
3 itso.wasdb.persis 
3 itso.wasdb.userpi 
3 ITSO_EJBsEJBF_ 
Java class libraries 1 
JFC class libraries 1. 
v1umpitz(6/2/99 5:40:1 
3 Default package •” 
IB 0 >Mumpitz-*^i 
Sun dass libraries PI 
Sun JFCDBDemos 1 
Sun JFC FileChoose 
Sun JFC Metalworks . 
Sun JFC Notepad 1 C ■ 
Sun JFCSampleTreu 
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Export... 

R eferences T o 

Replace With 

Delete... 

Reorganize 

Manage 
Compare With 
Run 

Document 
Externalize Strings.. 


Properties 


private static final Strir 
private static final Strir 
private static final Strir 


Command Editor... 

Create Servlet 

D omino AgentR unner ► 

ET/400 ► 

ET /Workstation ► 

Externals CM ► 

Mapper Editor... 

Migration Assistant 

Records ► 

RMI - Generate Stub and Skeleton 
San Francisco wizard 


Servlet Launcher 


Visual Servlet: Repair 

Visual Servlet: Scan For Problems (see Log) 


Properties 


F i gure 46. Launching a S ervl et 


2. Using WebSphere and the HTTP Server 

P\acetheConnMgrTest.html and the U dbConnMgr.d ass file under the 
proper directories. The HTM L file has to be placed in the path where the 
Web server can find it. Using the default installation the HTM L file 
should be placed under c: \Program Files\IBM HTTP Server\htdocs. 

The class file can easily exported with Visual Age for J ava. From the 
context menu of the servlet class select Export.... I n the following dialog 
select Directory for the export destination, click N ext and specify the 
export path. If you use the default installation of WebSphere this is 
c:\HebSphere\AppServer\servlets. Makesureyou select at least the cl ass file 
to be exported (Figure 47). 
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For more information about the proper directory location refer to 
"Configuration" on page 4 and "WebSphere Configuration” on page 6. 



D irectory: | c: \W ebS phereSAppS er ver\ser vlets\ 

Browse... 

What do you want to export? 



|7 .class 

Details... 

| 1 selected 


|7 java 

Details... 

| 1 selected 


(7 resource 

Details... 

| 0 selected 



Figure47. Exporting a Servlet 

Next goto http: //<server-name>/ConnMgrTest.html from the HTM L page and 
select the database sample you wish to run (you have to export all servlet 
examples first). 


DbaseConnMgr Class 

This class takes care of all function directly involved with the connection 
manager. The following is the class declaration for the DbaseConnMgr class 
(Figure 48). We then used subclasses for the three different DBMSs. 


package itso.wasdb.connmgr 


import java.sql 
import java.io.*; 
import javax.servl et.*; 
import javax.servl et .http.*; 
import com. i bm.servl et.connmgr.*; 


public abstract class DbaseConnMgr extends HttpServlet { 


private static final String SELECT = "Select empno, lastname, 
from i tso.empl oyee A, itso. department B where A.workdept = 
ORDER BY A. EMPNO ,B. DEPTNO" ; 

deptname, mgrno 

B .deptno 

protected IBMJdbcConnSpec connSpec = null; 
protected IBMConnMgr connMgr = null; 


private IBMJdbcConn ibmConn = null; //Connection used for Select statement 

private static final String USER = "itso"; 
private static final String PASSWORD = "itso"; 

} 



Figure 48. DbaseConnMgr Class Declaration 


The init method initializez the servlet when it is first loaded (Figure 49). 
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public void init(ServletConfig config) throws ServletException { 
super. init(config) ; 

initConnection(getPoolName() , getDriver(), getUrl()); 

} 


Figure49. DbaseConnMgr i nit Method 

The ini tConnecti on method creates a connection manager specification and 
obtains a static reference to the connection manager object (Figure 50). 


private void initConnection(String poolName, 
String driverName, 

Stri ng url ) { 

connSpec = new IBMJdbcConnSpec (pool Name , 

true , 

dri verName, 
url , 

USER 

PASSWORD ); 

connMgr = IBMConnMgrUti 1 ,getIBMConnMgr() ; 

} 


F i gure 50. D baseC onnM gr i ni tC on need on Method 

The getConnection method gets an IBMJ dbcConnection object from the 
connection pool and returns ajava.sql. Connect! on. This connection is used for 
the actual SQL statement (Figure 51). 


public Connection getConnection() throws SQLExcepti on, IBMConnMgrExcepti on { 
Connection conn = null; 

ibmConn = (IBMJdbcConn)connMgr.getlBMConnection(connSpec) ; 
conn = ibmConn. getJdbcConnecti on () ; 

return conn; 


F i gure 51 . D baseC onnM gr getC on need on Method 

The releaseConnecti on method releases the IBMJ dbcConnection object into 
the connection pool (Figure 52). 
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public void rel easeSel ectConnection () throws IBMConnMgrException{ 
ibmConn. rel easelBMConnecti on () ; 

} 


Figure 52. DbaseConnMgr releaseConnection Method 

The executes elect method creates an SQL statement using the connection 
obtained from the connection manager and executes it. The result of the 
execution is passed on to an output formatting routine (Figure 53). 


public void executeSelect(PrintWriter out) throws SQLException { 

Statement stmt= selConn.createStatement() ; 

ResultSet rs = stmt.executeQuery(DB2_SELECT) ; 

outputInfo(rs , out); 

} 

Figure 53. DBaseConnMgr executes elect Method 

The output I nfo method reads the ResultSet produced by the executeSdect 
method and places it inside a table on the HTM L page (Figure 54). 


public void outputInfo(Resul tSet rs , PrintWriter out) throws SQLException{ 

out.println("<TABLE B0RDER=3 FRAME=ALL C ELLPADDI NG= 1 CELLSPACINGS C0LS=4>"); 
out.println("<CAPTION ALIGN=TOP><b>UDB - Employee Info</b></CAPTION>") ; 

out.println("<TR>") ; 

out.println("<TH ALIGN=CENTER WIDTH=20%>Emp Number "); 
out.println("<TH ALIGN=CENTER WIDTH=20%>Last Name "); 
out.println("<TH ALIGN=CENTER WIDTH=20%>Dept Name "); 
out.println("<TH ALIGN=CENTER WIDTH=20%>Mgr Number "); 

whi le(rs .next() ) { 

out.print("<TR><TD ALIGN=CENTER>" + rs.getString("EMPNO")) ; 
out.print("<TD ALIGN=CENTER>" + rs.getString ("LASTNAME") ) ; 
out.print("<TD ALIGN=CENTER>" + rs.getString ("DEPTNAME") ) ; 
out.print("<TD ALIGN=CENTER>" + rs.getString("MGRNO")) ; 

} 

out.println("</TABLE>") ; 

} 


Figure 54. DBaseConnMgr output! nfo M ethod 

The doGet method is called from the Web server when the servlet is started 
from the FITM L page (Figure 55). 
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public void doGet (HttpServl etRequest req, HttpServl etResponse res) throws 
Servl etExcepti on, IOException { 

res.setContentType("text/html ") ; 


PrintWriter out = res.getWriter() ; 
try { 

out .printl n ("<HTML><HEAD><TITLE>ConnMgr Test</TITLE>") ; 
out.println("</HEAD><BODY>") ; 
executeSel ect(out) ; 
rel easeConnecti on() ; 

} catch (SQLException sql Except) { 

out.println("<hl> EXCEPTION IN SAMPLE CODE </hl> <p>"); 

out .printl n ("Error : " + sql Except. getErrorCodeO ) ; 
out .printl n ("State: " + sql Except. getSQLState() ) ; 
sql Except. printStackTrace(out) ; 
out.println("<HTML><BODY>") ; 

} catch (IBMConnMgrException mgrExcept) { 
if (out != null) { 

out.println("<hl> EXCEPTION IN SAMPLE CODE </hl> <p>"); 

out.println("<b>" + mgrExcept. getReason() + "</b>"); 
out.println(mgrExcept) ; 
mgrExcept. printStackTrace(out) ; 

} else { 

System. out. println(" EXCEPTION IN SAMPLE CODE "); 

System.out.pri ntl n (mgrExcept) ; 
mgrExcept. printStackTrace() ; 

} 

out.println("</BODY></HTML>") ; 



Figure 55. doGdc M ethod 


Note 

The code for the three databases mentioned below is the same, with the 
exception of the constants used to describe their database, connection pool, 
and driver name. To avoid repetition we will review all the methods for 
DB2 and will go through specifics of theother two databases. 
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DB2 


Before you start make sure your database is set up properly, see "DB2 UDB 
I retaliation” on page 22 for more information. 

The package in which the connection manager classes reside is 
/ bm.servt et. conn mgr. The following isthe class declaration for the 
U dbConnM gr class. It is here where the constants for the specific database 
and connection pool are specified (Figure 56). 


package itso.wasdb.connmgr 

Jkk 

* This type was created in Visual Age. 

*/ 

public class UdbConnMgr extends DbaseConnMgr{ 

private static final String DB2_P00LNAME="JdbcDb2" ; 

private static final String DB2_URL = "jdbc : db2 : i tsowdb" ; 

private static final String DB2_DRIVERNAME="C0M.i bm.db2. jdbc.app.DB2Dri ver" ; 


Figure 56. UdbConnMgr Class Declaration 

The getDriver method returns thej DBC driver name (Figure 57). 


public String getDriver() { 
return DB2_DRIVERNAME; 

} 


F i gure 57. U dbC onnM gr getDri ver Method 

The getPoolName method returns the pool name (Figure 58). 


public String getPool Name() { 
return DB2_P00LNAME; 

} 


Figure 58. UdbConnMgr gdiPool N ame M ethod 
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The getUrl method returns the U RL (Figure 59). 


public String getUrl () { 
return DB2_URL; 

} 

F i gure 59. U dbC onnM gr getU rl Method 

Sample Output 

The result of the run of this servlet is shown in Figure 60. 



F i gure 60. C on need on M anager Output 
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Oracle 


Before you start make sure your database is set up properly (see "Oracle 8 
I installation” on page 27). 

Thefollowing is theclass declaration for the OracleConnMgr class. Here is 
where the constants for the specific database and connection pool are 
specified (Figure 61). 


/kk 

* This type was created in Visual Age. 

*/ 

public class OracleConnMgr extends DbaseConnMgr { 

private static final String 0RACLE_P00LNAME = "JdbcOracl e" ; 

private static final String ORACLE_URL = "jdbc:oracl e:thin :@1 ocal host : 1521 : Orel " ; 
private static final String ORACLE_DRIVERNAME = "oracl e. jdbc.dri ver.Oracl eDri ver" ; 

} 


Figure 61. OracleConnMgr Class Declaration 

The rest of the code is the same as that described in "DB2”on page 77. The 
only difference is that, inside the code, the DB2_ constants arereplaced with 
the ORACLE _ set of constants. 

Microsoft SQL Server 

Before you start, make sure your database is set up properly (see "SQL 
Server I nstallation"on page 33). 

Thefollowing is theclass declaration for the SqISrvConnMgr class. Here is 
where the constants for the specific database and connection pool are 
specified (Figure 62). 


Jkk 

* This type was created in Visual Age. 

*/ 

public class SqISrvConnMgr extends DbaseConnMgr { 

private static final String SQLSRV_POOLNAME = "JdbcSql server" ; 

private static final String SQLSRV_URL = "jdbc : odbc : Sql Server" ; 

private static final String SQLSRV_DRIVERNAME = "sun. jdbc. odbc. JdbcOdbcDriver" ; 

} 


Figure 62. SqISrvConnM gr Class Declaration 

The rest of the code is the same as that described in “DB2”on page 77. The 
only difference is that, inside the code, the DB2_ constants arereplaced with 
SQL SR V _ set of constants. 
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8 Data Access Beans: 
VisualAge for Java 

I n this chapter we describe the IBM data access beans and their usage 
through WebSphere. For moredetailed reading, refer to VisualAge for J ava 
Enterprise Version 2: Data Access Beans - Servlets - Cl CS Connector, 

SG 24-5265. 

Data access beans provide access to relational data. Using data access beans 
is the fastest, non-programming way of building SQL queries accessing 
existing databases. J ust open the Visual Composition Editor, place a Select 
bean on thefree-form surface, specify the database connection and data you 
require, and you are ready. 

Most functionality is predefined. For example, your application can add, 
update, and delete rows, commit or rollback database transactions, handle 
multiple connections, lock rows, makethe access read only, and specify how 
many rows are fetched into memory (cache). 

An SQL Assist SmartGuide helps you tovisually specify the data you need. 
You can select one or more tables, join tables, define search conditions, 
restrict the number of columns, sort the result set, and changethe mapping 
between the SQL types in the database and thej ava types in the application. 
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In addition, an SQL Editor lets you enter SQL statements manually. Use this 
method when you need to compose very special or very sophisticated 
database queries. 1 

After you have defined your database access using a Select bean, you can 
place a DBNavigator bean into your visual application. The DBNavigator 
bean incorporates buttons that navi gate the result set of a query and perform 
various relational database operations. 

The Select bean fits into the J Table model of the new J ava Foundation 
Classes (J FC, called Swing). This relationship between retrieved SQL data 
and the Swing table model makes it very easy to develop attractive user 
interfaces for J ava applets and applications, based on standard J ava classes. 

With data access beans you have direct access to any database for which a 
J DK 1.1 compliant J DBC driver exists, for example, DB2 U niversal Database 
(UDB) Version 5. 2 Alternatively, you can use an ODBC driver together with 
thej DBC ODBC bridge that comes with the Sun J DK. 


Loading the Data Access Bean Feature 

Before you can use data access beans you have to add the data access bean 
feature to the Workbench. Use the Quick Start menu (F 2), select Features -> 
Add feature, and select IBM Data Access Beans 1.0 in the dialog that is 
displayed. This action loads the project into the Workbench and adds the 
data access beans to the beans paletteof the Visual Composition Editor. 


Data Access Beans and the Standard SQL Classes 

When using java.sql* set of cl asses, you are required to write all of the SQL 
code which sometimes can be a headache. Data access beans require less use 
of SQL and morej ava. Thefollowing shows the similarities between 
java.sql .* classes and data access beans (com.i bm.db.*) classes (Figure 63). 


1 SQL Editor generated code, in contrast to SQL Assistant generated code, cannot handle SQL parameters (host 
variables) because the statement is not parsed. The developer or the application code can add the parameter 
definitions manually to the generated methods to enable passing of values into the host variables. 

2 You can also use DB2 V2.12, plus the latest CSD. 
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java.sql. 


Data Access Beans Architecture 
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DatabaseConnection 
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PreparedStatement 


SelectStatement 


ResultSet 


SelectResult 


Figure 63. Data Access Beans Architecture 


DatabaseConnection and java.sql. Connection 

DatabaseConnection is a replacement for java.sql. Connection. It provides the 
same methods as its java.sql. Connection counter part. The connection can be 
managed internally or externally depending on which constructor is used. 

Internal Connection 

The DatabaseConnection default constructor provides a wrapping object 
around thej DBC connection for internal connection management. The 
internal management is rather simple. The connection that is created is 
shared by any application that makes a request to create a connection of the 
same name; it can connect and disconnect from the database at any ti me. 

With every request a counter gets incremented internally, and as objects 
disconnect, the counter is decremented. The object is released once the 
counter is dropped back to 0 (Figure 64). This way multiple applications 
share the same connection. Having this internal connection management is 
ideal for query based applications. 

If you are using an internal connection for update, you should be aware of all 
the applications with access to the connection, because any application with 
the connection can execute a commit or a rollback at anytime. Ifyou have 
several beans with access to same connection you have to ensure the 
sequence of access to the connection to prevent any loss or duplication of 
data. 
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Once all three applications 
disconnect() the object conn 
is closed. 


DatabaseConnection 



Figure 64. I nternal Connection Management by DatabaseConnection 

External Connection 

When using the DatabaseConnection (java. sql. Connection) constructor, the 
connection is considered to be externally managed. You can get this 
connection object from some other externally managed connection pool, such 
as I BM 's connection manager. You cannot issue the connect or disconnect 
methods against an externally managed connection (Figure 65). 



Figure 65. External Connection M anagement by I BM ConnectionM anager 
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Statement Types 

The cl ass com.ibm.db.SelectStatement represents an SQL select statement, 
which is roughly equivalent to both java. sql. Statement and 
java.sql.PreparedStatement cl asses. The Selects tatement always works with 
a helper object; an instance of com.ibm.db.StatementM etaData. 

Figure 66 shows the way in which these objects are constructed. A 
Selects tatement holds a StatementM etaData . A StatementM etaData is 
composed of SQL query text and column information. Note that multiple 
SelectStatements can sharethe same StatementM etaData, the information is 
read only from that perspective. 


SelectStatement 


StatementMetaData 


1 


QL Query Text 


Column Typing Information 


Figure66. Select Statement Design 


ResultSet Types 

There are certain drawbacks in using J DBC directly; the java. sql. ResultSet 
can only scroll forward, not backward. T he com. ibm.db.SelectResult cl ass of 
the data access beans is traversable both backward and forwards, and it also 
allows jumping to a particular index. TheSelectResult is already positioned 
at the fi rst row. 

The S el ectResu It reads the content of ResultSet into its structure. The 
SelectResult has the performance hit the first time it does that. The 
advantage of the SelectResult becomes apparent when there is a need to 
scroll up and down the ResultSet several times. 
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Building a Servlet using Data Access Beans 

We chose to usethe Servlet Builder in VisualAgefor J ava tocreateour 
samples. There arethree samples in which each of them accesses a different 
DBMS: DB2, Oracle and SQL Server. 

When describing the examples we avoided one-by-one steps involved in 
creating the servlet because there is a book dedicated to that topic. Please 
refer to Visual Age for J ava E nterprise Version 2: Data Access Beans - Servlets 
- CICS Connector, SG24-5265, for details about visual servlet construction. 


Sample Data Access Beans 

I n this sample the servlet takes a department number, and using a Select 
bean, it executes a query against the employee table and returns the list of 
employees into a list box. It also displays the number of employees within the 
department. For detailed information on the database tables structure, 
please refer to "Relational Database I nstallation and Setup" on page 21. 

Every database system has its own servlet class and Select bean. The servlet 
contains basic information on the parameters of the servlet, such as the 
department number entry field. The Select bean contains all of the 
information on the type of database, DB2, Oracle, or SQL Server, the tables 
involved, and the type of the query. No line of code is written to create this 
servlet. All of the code is generated by VisualAgefor J ava. All of the 
information on the tables and the beans is stored through a sequence of 
panels and dialogs, as part of the visual composition. 


Creating a Servlet Visually using Data Access Beans 

To create a servlet visually using data access beans, we create the visual 
servlet, tailor a Select bean for database access, and then construct the logic 
through connections in the visual composition. 

Visual Servlet 

To create the visual servlet follow these steps: 

□ C reate the new servl et cl ass U dbDabS ervl et i n the i tso. wasdb. accessbean 
package using Quick Start from the menu (F2). Use the servlet palette in 
the visual composition editor to design the HTML output page of the 
servlet. I n our example we use the same HTML page for input and output 
(Figure 67). 


86 


IBM WebSphere and VisualAge for Java Database Integration with DB2, Oracle, and SQL Server 



UDB Data Access Bean Servlet 



HtmlEntryField 

(deptnum) 

• HtmIForm 

-FltmlButton 

HtmITable 

HtmIText 


-FltmlResuItTable 


HtmIForm 


Figure 67. S ervl et User Interface 

□ Notice the naming of these beans: 

• The HtmIE ntryField is named deptnum 

• The HtmIText ...deptnum... is named deptresult 

• The HtmIText ...number.. .is named numemp 

• The Retrieve push button is named rdcrieveButton 

□ Save the servlet. This generates the underlying J ava code. In particular 
this creates a J avaBean (UdbDabServletFormData) that holds all the 
data of the data entry form, that is, the department number (deptnum) 
and the Retrieve push button. 

□ From the Servlet palette (Figure 68) select the For mD a ta bean and choose 
the UdbDabServletFormData as the class name in the dialog. This class 
was generated in thestep before. Place it somewhere outside the user 
interface of the servlet. This bean represents the actual data input which 
can be done in the user interface. I n our example, this bean contains as a 
property named deptnum the department value entered in the 
HtmlEntryField. 
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Methods [" 

© Compositic 



Figure 68. The Servlet Palette 

□ From the Database palette drag and drop a Select bean and name it 
U dbE mpl nDept (Figure 69). 


UDB Data Access Bean Servlet 


UDB Data Access Bean Servlet 

O 




Enter a department number: 


Retrieve | ;! 




o 

List of employees in department: 


. . . deptnum. . . 

O 







Lj 



<5 

Department has . . .number. . . employees. 


UdbDabServletFormDatal 


UdbEmpInDept 


Figure 69. Servlet with Data Access Bean and Select Bean 

Select Bean 

To tailor the database access you open the Select bean to specify the database 
connection and SQL statement. 

□ Doubleclick on the UdbEmpInDept bean. Select the query field and click 
on the grey box. Now you can set up a database connection and an SQL 
statement (F igure 70). 
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Figure 70. UdbEmpI nDept Connection Setup 

□ Click on the New button to create a new database access class 
(UdbDabAccess) that will hold the connection information and the SQL 
statement to be executed. 

□ Click on the Add button to add a connection to a database (Figure 71). 
Specify the U RL, the driver, the user I D, and the password. The name of 
the connection ( connect ) then becomes a method name in the database 
access class. 

By defining multiple connections it is possible to access different 
databases, or the same database with different user I Ds (and different 
rights) just by choosing another connection method. 
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Figure 71. Connection Alias Setup 

□ Test the connection (the DBMS must beup and running) and only proceed 
if you get a successful answer. 

□ Click OK" to generate the connect method into the database access class. 

□ Select th eSQL tab to set up an SQL query (Figure 72). 



Figure 72. UdbEmpi nDept SQL Setup 
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□ Click on the Add button and input theSQL A/amein the SQL 
Specification panel (Figure 73). This name becomes the name of the 
method that is generated into the database access class. 


jO]New SQL Specification 


SQL Name: | empindept 

Use SQL Assist SmartGuide (recommended) 
r Manuallywrite SQL 


a 


OK | Cancel | 


Figure73. Creating N&v SQL Specification 

In most cases, you will select the UseSQL Assist SmartGuide radio 
button. The SQL Assist SmartGuide enables you to build an SQL 
statement without much knowledge of SQL. You gothrough a set of pages 
to specify the tables, columns, and conditions of your SQL access. 

□ On the Tables page select the table(s) (Figure 74). 



F i gure 74. S el ecti ng a T abl e for the Query 
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□ On th eCondition 1 page you can create a WHERE clause with column 
specifications. To pass a variable as a value enter the name of a host 
variable (:DEPTNUM ) that will be set at execution time (Figure 75). You 
will recognize that if you enter a host variable beginning with a colon the 
name is printed in uppercase bold letters. 



Figure 75. Setting Query Con di ti on (s) 

□ On the Columns page select the columns to be retrieved (Figure 76). 
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Figure 76. Selecting Columns to I ndudefor a Query 

□ On th eSort page optionally select the columns used to sort the resulting 
rows. This creates an ORDER BY clause in the SQL statement. 

□ On the Mapping page you can perform simple conversions of SQL data 
types for yourj ava program, for example, converting numeric data to 
appropriate] ava data types. 

□ Th eSQL page displays the resulting query statement from thechoices 
made i n previous pages (Figure 77). 
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Figure 77. SQL Query Statement 

□ You can test the SQL statement by clicking on th eRun SQL button. You 
are prompted for the host variable value, the SQL statement is executed, 
and the results are displayed in a table. 

□ Click on Finish to generate the code. The SQL statement is added to the 
query (Figure 78). 
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Figure 78. Resulting SQL Query 

U p to this point, the setup for the servlet and the Sdect bean have been 
described. 

DBMS Selection 

This example was developed using the DB2 DBMS. To develop a servlet that 
uses another database, the same steps apply, except for the connection 
parameters. A different connection alias, appropriate for that database 
system, has to be provided (Figure 71 on page 90). 

We developed the same sample also for Oracle (OrclDabServlet) and SQL 
Server ( SqISrvDabServlet ). 

Logic Connections 

Figure 79 shows the final servlet after all the proper connections have been 
established between the objects and the user interface. 

Follow these steps to create the connections: 

1. Connect the retrie/eButtonPressed event of the UdbDabServletFormData 
bean to the execute method of the UdbE mpl nData bean. 
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2. Connect the deptnumString property of UdbDabServletFormDatal to the 
Parm_DE PTN U M _Stri ng property of UdbEmpI nDept. 

3. Connect the deptnumString property of UdbDabServletFormDatal to the 
string property of the ...deptnum... HtmIText bean. 

4. Connect the this property of the UdbE mpl nDept Select bean to the 
tableModel property of the HtmIResuItTable. 

5. Connect the executed event of the UdbE mpl nDept to the string property of 
the ...number... HtmIText. The result line is still dashed, meaning that a 
parameter is missing. 

6. Connect the value parameter of the previous connection to the numRows 
property of UdbEmpI nDept. 


UDB Data Access Bean Servlet 



Figure 79. UDB Servlet Using Data Access Beans: Visual Composition 
At this point you can generate the code and run it. 

Tailoring the Output Result Table 

By default the FITMLResultTablebear\ displays the long columns names, 
which, depending on the database, consist of the schema name, thetable 
name, and the column name. 

We modified the empindept method of the UdbDabAccess class to specify 
short column names (Figure 80). 
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Before: 

aSpec.addCol umn (" EMPLOYEE. EMPNO", 1,1); 
aSpec.addCol umri ("EMPLOYEE. FIRSTNME" , 12,12) ; 
aSpec.addCol umn ("EMPLOYEE. LASTNAME" , 12,12) ; 
aSpec.addCol umn (" EMPLOYEE. JOB", 1,1); 
aSpec.addCol umn ("EMPLOYEE. SEX" , 1,1); 
aSpec . addCol limn ( " EMPLOYEE . BI RTHDATE " , 91,91) ; 

After: 

aSpec. addColumn("EMPNO", 1,1); 
aSpec.addCol umn ("FIRSTNME", 12,12); 
aSpec.addCol umn ("LASTNAME", 12,12); 
aSpec. addColumn("JOB", 1,1); 
aSpec. addColumn("SEX", 1,1); 
aSpec. addColumn("BIRTHDATE", 91,91) ; 


Figure 80. Tailored Method with Short Columns Names 

Running the Servlet 

Figure 81 shows the result of the servlet in a Web browser. Start the 
WebSphereTest Environment (SE Runner class), then enter the U RL: 

http : //127. 0. 0. 1: 8080/servlet/ it so. wasdb.accessbean.UdbDabServlet 



F i gure 81 . Output R esul toftheS ervl et in a Web B rowser 
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Using the Connection Manager and Data Access Beans 

I n this section we develop an example servlet that uses both the connection 
manager to establish and manage the connections to the database system 
and a non-visual data access bean. 

The servlet function is to search for a record in the employee table, and 
display and update the record. 


Class Definition 

Thefirst step is the class definition in a new itso.wasdb.connaccess package 
(Figure 82). We coded the database access for all threeDBMSs, however, two 
are in comments. 


package itso.wasdb.connaccess; 

import com. i bm.servl et.connmgr.*; 

import com.ibm.db.*; 

import java.sql .*; 

import java.io.PrintWriter; 

import javax.servl et.*; 

import javax.servl et. http.*; 

public class Empl oyeeServl et extends javax.servl et. http. HttpServl et { 
com. i bm.servl et.connmgr. IBMConnSpec connSpec = null; 
static com. i bm.servl et.connmgr. IBMConnMgr connMgr = null; 


fi nal 
fi nal 
fi nal 
/* 

fi nal 
fi nal 
fi nal 


static String POOLNAME = "JdbcDb2"; 
static String URL - " jdbc: db2 : i tsowdb" ; 

static String DRIVERNAME = "COM. ibm.db2. jdbc. app.DB2Dri ver" ; 
static String POOLNAME = "JdbcOracl e" ; 

static String URL = "jdbc:oracl e; thin :@1 ocal host : 1521 rorcl" ; 
static String DRIVERNAME = "oracl e. jdbc. dri ver. Oracl eDri ver" 


final static String POOLNAME » "JdbcSql server" ; 
final static String URL = "jdbc: odbc : Sql Server" ; 
final static String DRIVERNAME = "sun. jdbc. odbc. JdbcOdbcDri ver" ; 
*/ 


final static String USER = "itso"; 
final static String PASSWORD = "itso"; 
final static String SELECT = 

"SELECT EMPNO, FIRSTNME, LASTNAME, JOB, SEX FROM ITSO . EMPLOYEE 
WHERE LASTNAME = : LNAME" ; 


StatementMetaData metaData = null; 


Figure 82. E mployeeServlet Class Declaration 
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Theclass declaration has nothing really fancy in it. As most servlets it is 
derived from HttpServlet, it defines the connection parameters, the user I D 
and the password. This can be easi ly changed, or even better, the servlet 
might read this from a property file. I n the last line a StatementM eta Data 
Object is declared. This object will contain all information for thequery and 
in the same turn also for the update of the database. 


Initialization 

The next part is the init method. The main purpose of this method is to 
initialize the connection manager and to create the StatementM etaData 
object (Figure 83). 


public void init(ServletConfig config) throws ServletException { 
super. init(config) ; 

// Specify the connection, now for simplicity this is hardcoded 
// It would be nicer to read this from a property file 
connSpec = new IBMJdbcConnSpec (POOLNAME, 

true, 

DRIVERNAME, 

URL, 

USER, 

PASSWORD) ; 


// Now get the static instance of the Connection Manager 
// from the Utility Class if not already done 
if (connMgr == nul 1) 

connMgr = IBMConnMgrUti 1 .getIBMConnMgr() ; 


// Next step is to prepare the Statement which will be run 
// agains the database. Therfor create the MetaData Object 
metaData = new StatementMetaData() ; 

// Spefify the select statement for the metaData 's SQL statment 

metaData. setSQL(SELECT) ; 

try{ 


// Define the input parameter with the type of class we use 
// for input (String) and the the SQL source type (CHAR) 
metaData. addParameter("LNAME" , Stri ng.cl ass , Types .VARCHAR) ; 

// Next define all ouput parameter in the same way 
metaData. addCol umn("EMPN0" , String. cl ass , Types. CHAR); 

metaData. addCol umn ("FIRSTNME" , String. cl ass , Types .VARCHAR) ; 
metaData. addCol umn ("LASTNAME" , String. cl ass , Types .VARCHAR) ; 
metaData. addCol umn ("JOB" , String. cl ass. Types. CHAR); 

metaData. addCol umn ("SEX" , String. cl ass , Types. CHAR); 

// Define the table name which is used in the query 
metaData . addTabl e ( " ITSO . EMPLOYEE " ) ; 

} catch (DataExcepti on e) { 

System. out. pri ntl n ("Error: " + e. toString () ) ; 
throw new Servl etExcepti on (e. toStri ng() ) ; 


Figure 83. E m pi oyeeServI et init M dihod 
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In the first part a new database connection is specified. The connection 
consists of the constants we saw already in Figure 82. Afterwards a new 
static reference to the connection manager is created, if not already there. 

I n the second part a new StatementM etaData object is created. The SQL 
select statement (see Figure 82) is then passed to this object. Notice the last 
part of the SELECT statement: 

" WHERE LASTNAME = : LNAME" 

This variable LNAME will be later replaced by an actual value. Todothis, 
LNAME has to be specified as an input parameter, which is done in the next 
line. Moreover, it also specifies thej ava class that will be used to specify this 
parameter, and what the resulting SQL type is. If you observe any problems 
here refer to "Data Access Beans” on page 266. 

The next lines are quite similar except that now the output columns are 
specified. The arguments are the SQL column name, thej ava class that is 
used to represent this value, and the according SQL type. We will see later 
that it is useful to provide this information to allow a convenient access to the 
result set and, moreover, it is a nice way to update a row. 

Thelast line specifies the SQL tablethat contains all thegiven columns. 


Form Parameter Access 

The getParameter method is a helper method (Figure 84). 


public String getParameter(HttpServl etRequest request. String key) { 
String values[] = request. getParameterVal ues (key) ; 
if (values != null) 
return values[0] ; 
return nul 1 ; 

} 


Figure 84. E mployeeServlet getParameter Method 

This method is handy to retrieve the parameter given to a servlet in the 
request. It just returns the first valuefor a key from the request object given 
tothe servlet. For example, if the HTTP request is: 

http://myserver/Servlet?fi rstName=Tobias&l astName=Himstedt&fi rstName=Ami r 
then getParameter (request, "fi rstN ame") would return "Tobiah. 
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Form Processing 

The next thing to is to define doGet and doPost. Because they should do the 
same, we cal I the same performTask method so that we are free to use either 
HTTP-POST or HTTP-GET. The servlet works with both options (Figure 85). 


public void doGet (HttpServl etRequest request, HttpServl etResponse response) throws 
Servl etExcepti on, java. i o. IOExcepti on { 
performTask(request, response); 

} 

public void doPost (HttpServl etRequest request, HttpServl etResponse response) throws 
Servl etExcepti on, java. i o. IOExcepti on { 
performTask(request, response); 

} 


Figure 85. E mployeeServlet doGet and doPost Methods 

Both methods call the performTask method, which itself is also very simple. 
Depending on the request, it either calls the method to retrieve the data for 
an employee or to update the data (F igure 86). 


public void performTask(HttpServletRequest request, HttpServl etResponse response) 
throws Servl etExcepti on, java.io.IOException { 

String command = getParameter(request, "command"); 

if ( command == null || command. equal s ("getEmpl oyee") ) 
getEmployeefrequest, response); 
else if (command. equalsC'updateEmployee")) 
updateEmpl oyee(request, response) ; 

} 


F i gure 86. E mpl oyeeS ervl et performT ask Method 

Based on thevaluefor the command parameter in the HttpS ervl etRequest 
object, performTask either calls getEmpl oyee to fetch a specific row from the 
employee table or updateEmpl oyee to update an already fetched row. 
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Employee Retrieval 

The getE mployee method processes the retrieval of an employee (F igure 87). 


public void getEmployee(HttpServletRequest request, HttpServl etResponse response) 
throws Servl etExcepti on, java.io.IOException { 

IBMJdbcConn conn = null; 

Connection jdbcConn = null; 

SelectResult resultSet = null; 

response. setContentType("text/html ") ; 
response. setHeader("Pragma" , "no-cache") ; 
response. setHeader("Cache-Control ", "no-cache") ; 
response. setDateHeader("Expires" , 0) ; 

// Get the output writer 
PrintWriter out = response. getWri ter() ; 

// Get the lastName paramenter for query 

String queryName = getParameter(request, "lastName"); 

out .printl n ("<HTML><HEAD><TITLE>ConnMgr / DataAccess</TITLE></HEAD><BODY>") ; 


F i gure 87. E mpl oyeeS ervl et getE mpl oyee Method (I ) 

What is happening so far is not very exciting. Basically, the response is 
specified, the caching is disabled, the output PrintWriter is created from the 
response object, and the parameter for the database query is detected. Next 
the beginning of the result page is printed to the PrintWriter. 

The next part retrieves a connection to the database based on the 
specification made in the init method (see Figure 83) from the connection 
manager. From this connection a J DBC connection is created. This is used to 
create a DatabaseConnection used for the data access beans (Figure 88). 


try { 

// Get the connection from the connection managers pool 
conn = (IBMJdbcConn) connMgr.getlBMConnection(connSpec) ; 

// Get the JDBC connection object 
jdbcConn = conn.getJdbcConnectionQ ; 

// Now use this JDBC connection for the creating 
// a connection usable by the data access beans 

DatabaseConnection dataConnection = new DatabaseConnection(jdbcConn) ; 


F i gure 88. E mpl oyeeS ervl et gdcE mpl oyee Method (II) 

The next part is about how to use the DatabaseConnection object to create a 
SelectStatement based on the SelectM eta Data initialized in the init method 
(Figure 89). 
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To execute the query against the database the query has to be completed with 
the actual query value. The value is retrieved from the servlet request 
(Figure 87 on page 102) and is then passed as parameter LNAME to the 
query. Now the query is ready to execute. After execution theresultSet is 
retrieved. 


Sel ectStatement select = new Sel ectStatement() ; 
sel ect .setConnecti on (dataConnecti on) ; 
sel ect .setMetaData (metaData) ; 

sel ect.setParameter("LNAME" , queryName) ; 

sel ect.execute() ; 

resultSet = sel ect.getResul t() ; 

Figure 89. getEmployee Method (III) 

In Figure 90 the values for the columns are retrieved. Based on the column 
values the FITM L output is generated as a table with a form in it. This 
enables the user to enter values for all the fields except for the primary key. 


String empNo = resul tSet .getCol umnVal ueToString ("EMPNO") ; 

String firstName = resul tSet.getCol umnVal ueToStri ng("FIRSTNME") ; 

String lastName = resul tSet.getCol umnVal ueToString ("LASTNAME") ; 

String job = resul tSet.getCol umnVal ueToStri ng("J0B") ; 

String sex = resul tSet.getCol umnVal ueToStri ng("SEX") ; 
out.println("<TABLE>" + 

"<F0RM ACTION = \"/servl et/i tso.wasdb . connaccess . Empl oyeeServl et\">" ) ; 
out.println("<TR>") ; 
out.println("<TH>Emp Number"); 
out.println("<TH>First Name") ; 
out.println("<TH>Last Name"); 
out.println("<TH>Job") ; 
out.println("<TH>Sex") ; 

out.println("<TR><TD>" + empNo); 

out. printing" <TD><INPUT TYPE=TEXT NAME=firstName VALUE=\"" + 
fi rstName.trimO + 

out.println(" <TD><INPUT TYPE=TEXT NAME=1 astName VALUE=\"" + 
lastName. trim() + 

out.println(" <TD><INPUT TYPE=TEXT NAME=job VALUE=\"" + 
job.trim() + 

out.println(" <TD><INPUT TYPE=TEXT SIZE=1 NAME=sex VALUE=\"" + 
sex.trim() + 

out.println("<TR><TD><INPUT TYPE=HIDDEN NAME=command VALUE=updateEmployee>") ; 
out.println("<TD><INPUT VALUE=Update TYPE=SUBMIT>") ; 
out.println("</FORM></TABLE>") ; 


F i gure 90. E mpl oyeeS ervl et getE mpl oyee Method (IV) 
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Notice the action attribute of the FORM tag. It points back to the same 
servlet. I n the source code this might look a bit wild, but as HTM L output in 
the browser, it is straightforward and is shown in Figure 91. 



Figure 91. Output of thegetE mployee Method 

Continuing with the servlet code we have one more important thing to do. We 
store the resultSet in a session object associated with the servlet request. 
This enables us later to use this resultSet to update the row (Figure 92). 


HttpSession session = request. getSession(true) ; 
session.putVal ue("i tso.wasdb.connaccess. Empl oyee.resul tSet" , 
resul tSet) ; 


F i gure 92. E mpl oyeeS ervl et get £ mpl oyee Method (V) 

The last part contains the error handling statements (Figure 93). 


} catch (IBMConnMgrException e) { 

System. err. pri ntl n ("Error: " + e.toStringO) ; 
e.printStackTrace(out) ; 

} catch (DataExcepti on e) { 

System. err. pri ntl n ("Error: " + e.toStringO); 
out.println("<H2>Error: " + e.toStringO + "</H2>"); 
e.printStackTrace(out) ; 

} 

out . pri ntl n ( "</B0DY></HTML>" ) ; 


Figure93. E mpl oyeeS ervl et get£ mpl oyee M ethod (VI) 
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Employee Update 

After retrieving an employee, the user can update the column values. The 
updateE mployee method performs the processing. The method begins with 
some administrative code (Figure 94). 


SelectResult resultSet = null; 

response. setContentType("text/html ") ; 
response. setHeader("Pragma" , "no-cache") ; 
response. setHeader("Cache-Control ", "no-cache") ; 
response. setDateHeader("Expires" , 0) ; 

// Get the output writer 
PrintWriter out =. response. getWri ter() ; 

out .printl n ("<HTML><HEAD><TITLE>Resul t</TITLE></HEAD><BODY>") ; 


Figure94. E m pi oyeeServId: updateE mployee Method (!) 

I n Figure 95 the session we created (see Figure 92) is now retrieved from the 
servlet request. I n this session we have stored the resultSet of the query. 


HttpSession session = request .getSession (fal se) ; 
resultSet = (SelectResult) 

ses sion. get Val ue ( " i tso.wasdb.connaccess. Empl oyee. resul tSet") ; 


Figure95. Em pi oyeeServId: updateE mployee Method (II) 

Next we retrieve the values from the input fields (Figure 96). 


String lastName = getParameter(request, "lastName") ; 

String firstName = getParameter(request, "firstName") ; 

String job = getParameter(request, "job"); 

String sex = getParameter(request, "sex"); 

Figure96. EmployeeServlet updateE mployee Method (III) 

Now we are ready to perform the update (Figure 97). If the values were 
given, they are passed to the resultSet of the query retrieved by the 
getEmpI oyee Method. Finally the row is updated and closed; also the 
connection manager is informed that theconnection is released. 
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try { 

if (lastName != null) 

resul tSet .setCol umnVal ue(" LASTNAME" , 1 as t Name) ; 
if (firstName != null) 

resul tSet .setCol umnVal ue("FIRSTNME" , firstName) ; 
if (job != null) 

resul t Set .setCol umnVal ue(" JOB" , job) ; 
if (sex != null) 

resul t Set .setCol umnVal ue(" SEX" , sex) ; 

resul tSet.updateRow() ; 

resultSet.closeO ; 

conn. rel easelBMConnecti on ( ) ; 


Figure97. EmployeeServlet updateEm pi oyee Method (IV) 

The last part contains the error handling statements (Figure 98). 


} catch (DataExcepti on e) { 

System. err. pri ntl n ("Error: " + e.toStringO ) ; 
out.println("<H2>Error: " + e.toStringO + "</H2>" ) ; 
e.printStackTrace(out) ; 

} 

out .pri ntl n ("<Hl>Update successful 1 </H2>") ; 
out.println("</BODY></HTML>") ; 


Figure98. EmployeeServltf updateEm pi oyee Method (IV) 


Testing the Servlet 

To test the servlet you may want to use to WebSphere Test Environment 
provided by Visual Age for J ava (start the SE Runner class). 

Open a browser and enter the U RL: 

http://127.0.0. 1 : 8080/s ervl et/i tso.wasdb.connaccess. Empl oyeeServl et ? 1 astName=LEE 

Alternatively you can launch the servlet from VisualAge for J ava. Before 
launching the servlet, you can setup the query parameter (host variable) in 
the servlet properties so that an employee is found in the table. 

From the context menu of EmployeeServlet select Tools -> Servlet Launcher 
->Properties to display the servlet launcher properties dialog and enter the 
values shown in Figure 99. 
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Figure99. Properties for the Employee Servlet 

After launching the servlet the browser should appear as shown in Figure91 
on page 104. You may then enter the text fields to update the data base. If the 
update was successful, the servlet will let you know with a message. 


Deploying Servlets to WebSphere 

For detailed instructions on deploying servlets to WebSphere, see chapter 20 
of the I B M redbook Visual Age for J ava E nterprise Version 2: Persistence 
Builder with GUIs, Servlets, and J ava Servlet Pages, SG24-5426. 

An example of deployment of a servlet to WebSphere is described in 
"Deploying a Servlet to WebSphere” on page 128. Make sure that the 
c:\IBMVJava\eab\runtime20\ivjdab.jar file is part of the WebSphere class path. 
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9 Persistence Builder: 
VisualAge for Java 

In this chapter we discuss the use of relational databases to provide 
persistence for J ava objects. We will use the VisualAge for J ava Persistence 
Builder tool to create persistent classes based upon existing database tables. 
We will use our ITSOWDB database as described in Chapter 4, "Relational 
Database I nstallation and Setup” on page 21. 

For these examples, the Persistence Builder tool must be added to your 
workspace. You can add the feature from Fiie->Quick Start -> Features -> 
Add Feature-> Enter prise Access Builder for Persistence. 

Notice 

If you have already added the WebSphere Test Environment feature, the 
Persistence Builder feature will report an error when thefeature is added. 
As the error message indicates you must remove the Websphere Test 
environment feature, then add the Enterprise Access Builder for 
Persistence feature again. This will alsoinstall the WebSphere Test 
E n vi ron ment for you . 


©Copyright IBM Corp. 1999 
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What is Persistence? 

In J ava, as with all programming languages, the state of an object is lost 
when the object finishes execution, unless the state of the object is 
externalized before execution is complete. This is true for any information 
which a program utilizes. I n J ava, saving the state, or any information, 
before program completion and restoring the state, or retrieving information, 
when the object is instantiated again, is known as persistence. 

J ava persistence can be achieved by serializing an object. That means 
converting the object's state into a sequence of bytes, then storing the bytes, 
which can later be read to resurrect the original object. This way an object 
does not need to know how to access a file to retrieve data itself; instead, 
whoever calls the object resurrects the entire object, including any data and 
the object state. 


Using Databases to Provide Persistence 

Databases can also be used to provide persistence for J ava objects. The 
object's state can be stored in a traditional SQL database and then 
resurrected by querying the database. The Persistence Builder is a Visual Age 
for J ava tool which guides you through the creation of classes that provide 
persi sten ce f u n ct i on a I i ty. 

Although thetool can be used to create persistent objects from scratch, one of 
Persistence Builder’s most powerful abilities is to take an existing database 
and create a persistent J ava application using the existing design of that 
database. Thetool includes all of the relations between tables and database 
rules in its design. It creates object definitions based on your tables, which 
can be used in yourj ava applications. 


Persistence Builder Tools 

For detailed instructions on using the Persistence Builder, review the 
redbook VisualAgeforJ ava Enterprise2: Persistence Builder with GUIs, 
Servlets, and J ava Server Pages, SG 24-5426. 

The tool has three major components used to defi ne how the tool wi 1 1 create 
yourj ava code for implementing object persistence. TheSchama, Model , and 
Mapping Browsers enableyou to define the table model, the object model, 
and the mapping between the two models. 
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Schema Browser 

The Schema Browser is used to import, create, view, and modify the 
relationships between the actual tables in your database. This browser is 
wherethe Persistence Builder gathers the necessary information (for 
example, column definitions, foreign key relationships) from your database to 
create objects based on the data stored within. Using your newly created 
schema, a model can be generated based on the schema. 

Model Browser 

The Model Browser creates the actual persistent classes whose data will be 
externalized. It adds to these objects attributes and associations from the 
schema. It is important that theschema truly represents your physical 
database to ensure that the objects can interact correctly with the actual 
database. I n our examplethe objects will be employee and department. 

Map Browser 

The Map Browser is used tocontrol mappings between thetables and the 
model classes. It is used to map theobject attributes and associations to the 
actual database tables. 


Vendor Specific Considerations 

As this book was written, the released version of Visual Age for J ava 
Persistence Builder only supported the importing of DB2 databases to create 
a persistent application's schema. 

A fixfor importing Oracleand SQL Server databases to create a schema was 
written as this book went to publishing. Thefix requires a package to be 
imported and a fileto be placed in your VisualAgefor J ava directory. With 
this fix, you can import the Oracle or SQL Server database and createthe 
proper schema. 

If your version of VisualAgefor J ava fails to import these schemas, contact 
VisualAgefor J ava support for the proper fixes. 
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Persistence Builder Example: Employees in Department 

We will attempt to take an existing database from DB2, Oracle, and SQL 
Server to create a simple persistent object model. Then we will create a 
servlet that uses this model. The servlet takes a department number as input 
and returns a list of employees within that department. Thefirst step is to 
create a schema for your objects based on your table. 


Import the Schema 

From your Workbench, open the Schema Browser by selecting Workspaces 
Tools -> Persistence Builder Tools ->BrowseSchema. Si nee we want to create 
our schema from an existing database, we use the import function. This type 
of design is also known as a bottom-up design because we are starting with a 
databaseand building our application around it. Select Schema ->lmport/ 
Export Schema -> Import Schema from Database Now enter the name you 
wish to call your schema; in our example, we call the schema ITSO. 

You must now enter thej DBC connection information (Figure 100). This 
connection information is dependent on the database vendor you are using as 
a datastore. The connection and driver specifications used here should relate 
to the information used to create a connection i r\ Chapter 5, "J ava Database 
Connectivity" on page 43. 



Figure 100. Importing a Schema 
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Once the connection is established, you select the tables you want to import 
from. Each table you want to import must be highlighted (use the shift key 
with the mouse for multiple selections) as in Figure 101. 



Figure 101. I mport Table Selection 

The Persistence Builder now generates the schema from the database and 
displays it in the Schema Browser (Figure 102). 

The schema is a representation of your actual database. You should look at 
each column's attribute by doubleclicking on the attribute and confirm that 
it is the correct type (Figure 103). 

It is alsoa good idea to inspect the foreign key relationships. It is important 
that all foreign keys from the table are displayed in the schema. If a 
relationship is not shown, createone based on the physical table in the 
database, otherwise the correct classes will not be created later on. 

We renamed the foreign key relationship to depts (Figure 102). When the 
schema is generated from your database, if theforeign key relationship is not 
given a name in your SQL statements, the schema browser uses the internal 
restraint name used by your database. To rename a relationship, use the 
relationship's context menu and select R m a me Foreign Key Relationship. 
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Figure 102. Schema Browser 



Figure 103. Schema Column Editor 
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Generate and Validate the Object Model 

The next step is to generate the model from the schema. Select Schemas -> 
Generate Model from Schema. The Persistence Builder builds a model of the 
objects based on the database schema. You should now open the M odel 
Browser. You can open it either from the tools menu from the Workbench as 
described earlier, or from the schema window, select Persistence Builder Tools 
->Model Browser. 

The Model Browser (Figure 104) is a view of the object model; instead of 
tables and columns it has classes and attributes. 



Figure 104. Model Browser 

Not all of the column specification from the schema transfers tothe object 
model. It is important to inspect the classes, attributes, and keys as well. 

Notice that the NOT NULL option of columns in the tables does not cause the 
Value required checkbox to be marked. You should open all of the attributes 
that map to columns that are not null (by doubleclicking on the class 
attribute to edit) and checking the Value required checkbox (Figure 105). 
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Figure 105. Attribute Editor: Marking the ValueRequired Field 


Inspect the Map 

Open the Map Browser (under Persistence Tools) to inspect the mapping 
from the schema to the model. If the model objects do not map properly to the 
physical database, the map browser will inform you. The map was created 
when you generated the model from the schema. It is important that the 
mapping is correct before you attempt to generate thej ava code, or some of 
the generated J ava methods will not function properly. I n the Map Browser 
select the generated DataStore Map, in this example/TSO/tso. 

I n Figure 106 we see a broken table mapping. I n this particular example we 
see an error converting the type of the table column to the cl ass attribute. If 
you open the table in the Schema Browser, we see that Employee, hi redate 
has a typeTIMESTAMP. If you then look in the Model Browser, the hi redate 
attribute has a type DATE. 
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Instance Variable: 'birthdate' in Employee 


Figure 106. Map Browser with a Broken Table Map 

We have two ways of fixing this mapping problem: we can change the 
mapping function by double clicking on the attribute in error, or change the 
type of one of the attributes in conflict. We chose to change the type of the 
hiredate attribute in the Model Browser to a type of java. sql. Timestamp. The 
error displayed in the M ap Browser is then cleared as in Figure 107. 



Figure 107. Model Browser 

If you have found any errors or made any changes in the Schema Browser, 
remember to regenerate the model based on the new schema. 
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Generate the Java Code for the Object Model 

Now that thethree browsers correctly define how you want your objects to 
behave, it is time to generate the actual code. From your Model Browser, 
select M odds -> Generate. Three options are presented in theSmartGuide 
(Figure 108). 



Figure 108. Generation Options 

Thefirst step is to generate the J ava classes and interfaces of the object 
model, which is thefirst radio button. The next panel prompts you for the 
project and package names. For our example, we used the i tso. w a sdb. persist 
package. 

As shown in Figure 109, you should markth e Generate Bound Beans 
Properties checkbox. Model classes with bound properties fire 
propertyChange events, which is useful when creating applications using 
visual construction. 
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Figure 109. Generation Options (Bean Properties) 

The next panel asks you which model elements you would I ike to generate; 
for our example, all of the elements. Click on th e Finish button and the 
classes are generated. 


Generate the Java Code for the Service Classes 

Now that theobject classes have been defined, it is necessary to generate the 
service classes that will handle the persistent aspect of your objects. The 
service cl asses are responsible for externalizing all of the information in your 
objects and later resurrecting those objects. 

FromtheModel Browser, select M odds -> Generate This time you will select 
the second radio button displayed in Figure 108 on page 118, Data Service 
Classes and I nterfaces. The next panel prompts you for the type of schema to 
generate. We are using the existing relational database to store the 
information, therefore we select thethird radio button, Relational SQL 
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(Figure 110). Enter the package name for the service classes, inourcase 
i tso. wasdb. per si st. S ervi ces. 



Figure 110. Schema Generation Selection 

After completing this panel, select Next to display the database connection 
information prompt. E nter the correct information to connect to the database 
(same as in Figure 100 on page 112) and then select the Generate queries 
using parm marker bindings checkbox (Figure 111). 
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Figure 111. Database Connection Information 


Next you will be prompted for the model elements to include, in our case all 
elements and then click on Finish. If you look in the Workbench, you will see 
that your packages have been successfully created. 

You arenow ready to build a persistent application, but first, save the model, 
schema, and map definitions in the itso.wasdb.persist.metadata package (use 
the File menu in each browser). 


Build the Servlet 

Now that all the classes are in place, you can create a visual servlet to 
interact with the persistent objects. From the Workbench, select Fiie->Quick 
Start -> Servlets ->Visual Servlet. You are prompted for the project, package, 
and name of servlet. Use a naming convention you feel comfortable with. We 
used the itso.wasdb.persist.gui package and we named the servlet 
EmpsinDept and selected a simple model to work with. 
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The next panel asks you the name of the servlet tousefor theAction form; we 
used the same servlet name. Click on Finish and the SmartGuide creates the 
classes and opens the visual composition editor. We will not go into depth 
concerning the use of the visual composition editor, instead wedisplay some 
of the steps and the resulting design. 

Visual Layout of the HTML Output Page 

We first have to create the HTM L output page itself. I n Figure 112, we have 
created the form to enter the department name. There are a few HtmIText 
beans, an HtmlEntryField that we named DeptEntryField, and a 
FI tml Push Button named DeptSubmitButton. The prompt, entry field, and 
button are within a three column, single row table. At the bottom we use 
another form with an FltmlResuItTable named E mpListResult. Save the 
design so that the FormData bean is generated. 

The composition of theservlet is very similar to theone given in "Creating a 
Servlet Visually using Data Access Beans" on page 86. 


Page 


o 


Employees in Department Servlet 


Please enter department number 


Retrieve 


o 

Employee List 

o 



Figure 112. HTML Output Page of a Servlet 
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Beans for Data Retrieval 

Next we placed the beans required for the logic. We select the FormData bean 
from the palette and select the E mpsl nDeptFomdata that was generated 
when saving the visual layout. This bean represents the HTM L form and has 
all the information and actions that can take place on the visual form. 

Because we are entering a department number, we have to retrieve the 
actual department object for that number. Ifwewant to find all employeesin 
a department, we start with the department object and follow the 
relationship to get the employees. To retrieve the department object we use a 
and enter the DeptHomeBean class from the itso.wasdb.persist package. 

Once that department object is found, it needs a place to be stored, therefore 
we pi ace a department object on the page as wel I . We use a transacted 
variableof typ e Department/-! omel mpl to represent the department retrieved 
through the home class. 

We now switch to the Persistence Builder palette to add the objects we will 
need to enact the persistence services. We select a read-only transaction bean 
because we are only reading information without any updates. We also use a 
VapDeFaultRelationshipTableModel bean to convert the list of employees into 
a displayableform. Both of these icons are in the palette (Figure 113). 



Figure 113. Visual Composition Editor with PersistenceBuilder Palette 
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Connections for the Logic 

Now that we have all the necessary beans, we must add the connections 
between the objects (Figure 114). 


Department Employees 



Connections: 

1. Retrieve the department when the form is submitted: 

E mpsl nDeptFormData(E vent DeptSubmitButton Pressed) to 
DepartmentFlom e(find(java.lang.String) method) 

2. Pass the department number entered to the find method: 

E mpsl nDeptformData(property deptE ntryF i el dStri rig) to parameter of 
find(deptno) 

3. Store the result of thefind method as a department object: 

Normal Resultto DepartmentHomel mp\ (this) 

4. Set the current transaction for the department: 

ReadOnlyT ransaction (this) to DepartmentFlomel mpl [transact! on) 

5. Set the current transaction for the employee result: 

ReadOnlyT ransaction (this) to 
VapDefaultRelationshipTableM od el (transaction) 

6. Retrieve the employees of the department: 

DepartmentFlomel mpl (property employee) to 
VapD efau I tRel ati onsh i pTa bl eM od el (relationship) 
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7. Display the employees of the department: 
VapDefaultRelationshipTableModel (this) to 
EmpListResultTable(tab/afWoc/e/) 

Tailor the Result Table 

After all of the connections are established, the properties of the 
VapDeFaultRdationshipTableModd have to be set. The bean needs to know 
which columns of data you want to display in the result table. Doubleclick on 
the object to access its properties, then alter the col umnldentifiers row (click 
on the little push button that appears in the row). Figure 115 shows the 
dialog used to set the object class and the properties (columns of the table) 
that we want to show i n the output. 



Figure 115. Column I dentifiers 

You must enter the full name of the class ( itso.wasdb.persist.E mployee) and 
then its properties aredisplayed automatically in the middle pane. Select the 
desired properties and click on Add to set the columns of the result table. 
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Notice 

The servlet does not activate the datastore you have created with the 
Persistence Builder tool. For the servlet to work, you must activate the 
datastore before doing any processing. The best place to add the datastore 
activation is the initialize method of the servlet: 

it so. wasdb . persist . Services . I TSO I tsoDataStore. singleton () . activate () ; 

The singleton method creates one instance of the datastore (independent of 
how many ti mes it is cal led), and the activate method starts the datastore. 
Place the statement after the comment line // user code begin fij.This 
code is preserved even if the method is regenerated. 


Test the Servlet 

Once you have completed all of these steps, your servlet should be ready to 
run. Press Ctrl-S to save your work and then click on the Run icon on the tool 
bar. This starts the WebSphere Test Environment (servlet runner) and 
displays the HTM L page with the default browser (Figure 116). 



Figure 116. Servlet Test Output 
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Changing the Datastore Database 

Once you have created the persistent servlet, it is possible to change which 
database manager product is used for persistent storage. You must duplicate 
the complete database in the new database manager product. The details of 
completing this task is beyond the scope of this book. 

To change the datastore, simply regenerate the services class of the 
persistent servlet from the Model Browser. This time specify the connection 
information for the new database manager product. 

Another way to change which database product is used as a datastore is to 
makeasmall manual change in thedatastore services class. The database 
connection information is stored in the getConnectionSpec method of the 
ITSOItscDataStore class in the itso.wasdb. persist. Services package. 

This code controls the driver and connection information that your object 
uses to communicate with the database. By changing the driver and 
connection information, we can change the database product, as long as 
identical tables exist in the different database managers. Figure 117 shows 
the correct settings for our example to interact with DB 2, Oracle, and SQL 
Server. Notethat this code is removed if you regenerate the service classes! 


//* WARNING: THIS METHOD WILL BE REGENERATED. */ 

public com. i bm. ivj .db. base. DatabaseConnecti onSpec getConnectionSpec() { 
DatabaseConnectionSpec aConnecti onSpec; 

DatabaseConnectionSpec forDB2, forOracle, forSQLServer; 

// DB2 UDB app driver 

forDB2 = new DatabaseConnectionSpec 

(" VA1 " , " COM .ibm.db2.jdbc. app . DB2Dri ver " , "jdbc:db2:itsowdb") ; 
// Oracle thin driver 
forOracle = new DatabaseConnectionSpec 

("VA1" ,"oracle. jdbc. driver. OracleDri ver" , 

"jdbc:oracle: thin :01ocal host : 1521: Orel ") ; 

// SQL Server jdbc/odbc bridge 
forSQLServer = new DatabaseConnectionSpec 

("VA1" ."sun. jdbc.odbc.JdbcOdbcDriver", "jdbc:odbc: SQLServer") ; 

aConnectionSpec = forDB2; 

// aConnectionSpec = forOracle; 

// aConnectionSpec = forSQLServer; 

aConnectionSpec. setLogonSpec(new DatabaseLogonSpec ("itso", "itso")); 
return aConnectionSpec; 


Figure 117. Establishing Connections toMultipleDatabaseVendors 
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Deploying a Servlet to WebSphere 

Your new servlet is ready to run on the WebSphere server, but you must 
make sure that all the proper resources are available on the Web server. For 
detailed instructions on deploying persistent servlets to WebSphere, see 
chapter 20 of the I B M redbook Visual Age for J ava E nterprise Version 2: 
Persistence Builder with GUIs, Servlets, and J ava Servlet Pages, SG24-5426. 

The first thing to move to WebSphere is the datastore. Be sure that the 
database tables and files are available on the WebSphere server. It is 
important that the database is identical to the database used in the test 
envi ronment. 

Next export all of the servlet code and copy it to WebSphere. I n our example, 
we created three packages which must be exported (Figure 118). Place all of 
these cl asses i n the WebSphere servl et di rectory. 



Figure 118. Exporting the Servlet 
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With the code moved to WebSphere, it is imperative that all of the classes 
that your persistent application utilizes are available in the WebSphere 
envi ronment. 

We do not go through all of the WebSphere administration pages. For now, 
the most important setting to get Visual Age for J ava servlets to work is the 
class path setting, and that is on th e Setup ->J ava Engine page (Figure 119). 



Figure 119. WebSphere Application Server: J ava E ngine Setup 


We used the following class path: 

D:\jdkl . 1.6\1 i b\cl asses.zip; 
D:\WebSphere\AppServer\cl asses ; 
D:\WebSphere\AppServer\web\cl asses; 
D:\SQLLIB\java\db2java.zip; 
D:\orant\Jdbc\lib\classeslll.zip; 
D:\IBMVJava\eab\runtime20\ivjdab.jar; 
D:\IBMVJava\eab\runtime20\i vjsb21 .jar; 
D:\IBMVJava\eab\runtime20\ivjpb20.jar; 
D:\IBMVJava\eab\runtime20\ivjpb20e.jar; 

D:\IBMVJava\hpj\l ib\swingall . jar; 


<=== JDK 

<=== export directory 

<=== DB2 JDBC Drivers 
<=== Oracle JDBC Drivers 
<=== data access beans 
<=== servlet builder 
<=== persistence builder 
<=== pers. builder extras 
(see below) 

<=== swing 
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To simplify the cl ass path, we copied thej AR files into the directory 
D:\UebSphere\AppServer\lib.l ar files in the lib subdirectory are automatically 
added to the WebSphere class path and do not have to be specified in the 
administration setup. 

Three of these J AR files are special cases: 

□ The ivjpb20ejar file is not provided by Visual Age for J ava. We built this 
file ourselves by exporting the Vi sual Age Persi stance E xtras project from 
Visual Age for J ava. This is the project with the additional classes to 
interact with AWT and Swing from Persistence Builder home and 

rel ationship collections. 

□ The ivjdab.jar file contains the same classes as the databean.jar file 
provided by WebSphere, plusextraGUI classes. To makesure that the 
ivjdab.jar file is loaded before the databean.jar file, we added it to the 
class path. 

□ The ivjpb20.jar file contains the same classes as the qs.jar file provided 
by WebSphere, plus extra classes. To make sure that tbeivjpb20.jar file is 
loaded before the qs.jar file, we added it to the class path. 

Your persistent servlet should successfully run in WebSphere with this class 
path setting. 
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Enterprise 

JavaBeans 


I n this chapter we will briefly discuss what EnterpriseJ avaBeans are and 
how they are used in conjunction with WebSphere, Visual Age for J ava, and 
databases. 

For further information refer to http://java.sun.com/products/ejb/docs.htnil or 
to the redbook Enterprise JavaBean Development with VisualAge for Java, 
SG24-5429. 

Note that EnterpriseJ avaBeans is the name of the architecture as specified 
by Sun; what we develop we will simply call enterprise beans. 


©Copyright IBM Corp. 1999 


131 



Enterprise JavaBeans from a Bird’s-Eye Perspective 

An EnterpriseJ avaBean is a nonvisual component which runs on the server 
side of a distributed application. Theenterprise bean itself lives in an 
environment called an EJ B container. The EJ B container in turn runs in an 
EJ B server or EnterpriseJ ava Server (EJ S). The goals of the EJ B 
architecture include: 

□ Making lifeeasier for thedeveloper: The developer does not have to 
struggle with low-level entities such as persistence, threads, and 
transactions; in that the EJ B architecture enables the developer to 
concentrate on the business logic. 

□ Making server applications portable: The model ensures that J ava 
platform server components can be developed once and deployed 
anywhere. 

□ Making the server application independent: The EnterpriseJ avaBeans 
architecture is completely independent from any specific platform, 
protocol, or middleware infrastructure. Applications that aredeveloped 
for one platform can be picked up, moved, and redeployed to another 
platform. 


A Closer Look 

So far we have seen the abstract term of enterprise bean, EJ B containers, 
and EJ B servers. We will now take a closer look at those terms. 

There are two types of enterprise beans: session beans and entity beans. 

□ Session beans can be stateful or stateless. Stateful session beans exist 
for the duration of a single client/server session. Stateless session beans 
are pooled by the container to handle multiple requests from multiple 
clients. 

□ Entity beans contain persistent data that can be saved in various 
persistent data stores. Each entity bean carries its own identity; that 
means entity beans do have pri mary keys. E ntity beans that manage thei r 
own persistence are cal led bean managed persistence (BM P) entity beans. 
Entity beans that delegate their persistence to the EJ B container are 
called container managed persistence (CM P) entity beans. 

The home interface specifies the available methods for locating, creating, 
and removing instances of enterprise bean classes. This is normally provided 
by thedeveloper. 
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The remote interface specifies the business methods of the enter prise bean. 
Typically, the developer of the enterprise bean also defines the remote 
i nterface. 

An EJ B container is a runtime environment that manages one or more 
enterprise beans. Specifically, containers manage the lifecycles of enterprise 
bean objects, coordinate distributed transactions, and implement object 
security. The deployment descriptor, a serialized object that contains 
run-time settings for an enterprise bean, tells the EJ B container how to 
manage and control an enterprise bean. Generally, each EJ B container 
contains a set of enterprise beans. EJ B containers are typically provided by 
EJ B servers. 

An EJ B server is a high-level process or application that provides a 
run-time environment to support the execution of server applications that 
use enterprise beans. An EJ B server providesaj NDI -accessible naming 
service, manages and coordinates the allocation of resources to client 
applications, provides access to system resources, and provides a transaction 
service. An EJ B server could be, for example, a database or application 
server. 


Developing a Container Managed Persistence Entity 
Bean 


I n this section we develop a simple enterprise bean. Because this book is 
about WebSphere and database integration, we develop this entity bean 
based on the employee/department sample that we are using throughout this 
book. For the development process we utilize VisualAge for J ava. Moreover 
we show how to deploy the enterprise bean touse it within WebSpherefrom a 
servlet, and we also show how to usethis enterprise bean from an applet or 
application. 


Notice 

I n our version of WebSphere Application Server (Version 2.0.2), and also in 
the WebSphere Test Environment of VisualAge for J ava, container 
managed persistence (CMP) only works with DB2 and not with Oracle and 
SQL Server. Therefore, this first example will only work with DB2. 

The next example uses bean managed persistence (BM P) and works with 
all J DBC compliant databases. 
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Setup of VisualAge for Java 

Follow these steps to set up VisualAge for J ava: 

□ Make sure you added the IBM EJ B Development Environment 1.1 feature 
to Visual Age for J ava. To see whether you have installed this feature, go 
to File ->Quick Start, select Features on the left side and DeleteFeature 
on the right side. This will show you all installed features (Figure 120). 



Figure 120. Avail able Features 

□ Add the feature if it has not been added to the Workbench. 

□ I n your project (we used ITSO SG24 5471 as the project name) create a 
new package called itso.wasdb.ejb. This will contain the enterprise bean 
we develop. 

□ Next go to the EJ B pane in the Workbench (Figure 121). 

□ Now create a new EJ B group in the EJ B pane. F rom the £7 Bs menu 
select Add ->EJ B Group. Select the project ( ITSO SG 24 5471) and give 
the EJ B group the name ITSO_EJ Bs. 
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Create a Department Enterprise Bean 

To create an enterprise bean: 

□ From thecontext menu of the new EJ B group select Add ->EJ B. Our first 
EJ B will be related to the department table already used throughout the 
book, so name the bean Department As we want the contai ner to manage 
the persistence service, select Entity Bean with container managed 
persistence fields (CMP) as the bean type. Select the project ( ITSO SG24 
5471) and th eitso.wasdb.ejb package (Figure 122). 
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Figure 122. EJ B SmartGuide 

I n the next dialog of the SmartGuide you do not have to make any 
changes, so click on Finish. 

□ The SmartGuide has now created a very basic framework for the EJ B. It 
should have created three interfaces and two classes: 

• Department interface: This currently offers no methods to be 
implemented. Later on, this will contain the abstract method 
declarations of all methods that will be implemented by the 
DepartmentBean class, which represents the business logic. 

• DepartmentBean class: This class will contain the actual business 
logic. The SmartGuide has already created several methods for this 
class, including a method that creates the EJ B. Because this is an 
entity bean, the SmartGuide also created a primaryKey property. 
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• Departments eanF i nderH d per interface: This should be empty at the 
current state. It might later contain specialized SQL search strings 
that allow a certain order within the various EJ B instances. 

• Department!-! ome interface: This contains a method to find a specific 
bean by its primary key or create a new bean with a new pri mary key. 

• DepartmentKey class: This class represents the primary key for the 
entity bean. For the Department table, this will be mapped to the 
DEPTNO column. 


Add the Properties and Methods to the Bean 

Now we add the actual properties and business logic to the skeleton classes. 

□ The properties are basically nothing but the columns from the department 
table. The business logic in this example is limited to get and set methods 
for the properties. Thedepartment tableconsists of the foil owing columns: 
DEPTNO, DEPTNAME, M GRNO, ADM RDE PT, and LOCATION. 
Therefore, the Departments ean contains the matching properties and also 
the get and set methods for the properties, except for the primary key 
property that should not be alterable. 

As described in the previous step, the SmartGuide already created a 
primary key property. Because it should match thedepartment table, the 
first action is to add the deptNo property and make it the primary key 
field. Highlight the Departments ean class in the Types pane and use the 
Create Field SmartGuide to add a public field named deptNo of type 
String. Let the SmartGuide to create a get method for this property, but a 
set property is not appropriate for a primary key (Figure 123). 



Figure 123. Adding a Field 
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□ Now make the deptNo field the primary key field. Click on the fields icon 
in the Type pane (Figure 124). The Types pane is now changed to a Fields 
pane. 

Here you see all the fields (properties) of the bean. It contains now three 
properties, the primaryKey property, an entityContext property, and the 
newly created deptNo property. The primaryKey property is currently the 
key field (it has the key icon on the right side) and it is a container 
managed field, identified by the cup-like icon on the right side. 




Figure 124. Switching to the Fields Pane 

To make the deptNo property the primary key, right-click on that deptNo 
entry and select Key Field. It should now show both icons, the cup and the 
key. 
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Now we delete the primaryKe y property generated by the SmartGuide by 
removing it from the bottom source pane. After deleting the primaryKey 
property, the qbCreate method in th e Methods pane reports a problem 
that we have to repair. I n the method body of qbCreatp replace 
primaryKey by deptNo (deptNo = key.deptNo;). 

□ Everything is now ready to add the rest of the properties. Switch back to 
the Types pane and select the Departments ean cl ass. U se the Create Field 
SmartGuide to add thedeptNamp location, mgrNo, and admrDept 
properties (all public, of type String, with getter and setter methods). 

□ By now your Methods pane should bea bit morefilled. Next, makeall the 
getter and setter methods available to the EJ B Remote I nterface. To do 
this, right click each getXXX and setXXX method, and select Add To- > 

EJ B Remote I nterface (Figure 125). After this, each method contains a 
little unidentifiable icon on the right, and the department i nterface offers 
all the methods you havejust added to the remote interface. 



Figure 125. Add Methods to the Remote I nterface 
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□ Next, mark all the properties we have defined to be persistent. Switch 
back to the Fid ds pane, right click on each field and mark it Container 
Managed (Figure 126). 
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Figure 126. Marking Properties Container Managed 


Map the Bean to the Schema 

The bean is persistent in the relational database. We import the database 
schema and map the properties of the bean to the columns of the department 
table. We describethis only briefly because wecovered schema mapping in 
detail in Chapter 9, "Persistence Builder: VisualAgefor J ava"on page 109. 

□ Start the Persistence Builder Schema Browser from the menu EJ Bs -> 
Open To -> Database Schemas. 

□ From the menu select Schemas ->lmport/ E xport Schema -> Import 
Schema from Database and name the new schema ITSO_Schema. 

□ Specify driver, URL, user ID, and password (Figure 127). 



Figure 127. Connection I nformation for theSchema Import 
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□ Build thetable list based on the ITSO qualifier and select the 
DE PARTM E NT table (F igure 128). 
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Figurel28. Select theTableto I mport 

□ We do not have to modify the imported schema (Figure 129). Close the 
Schema Browser. 



Figure 129. Schema Browser after I mport 
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□ After importing the schema we perform the mapping. Open the M ap 
Browser by selecting EJ Bs ->Open To->Map Schema. From the 
Datastore_M aps menu select New E) B Group Map. Name the map 
ITSO_Map, select the EJ B group and the schema (Figure 130). 



Figure 130. Specifying theDatastoreMap for the Enterprise Bean 

□ The next step is to associate the properties of the EJ B to the columns of 
the department table. Select Table_Maps ->New Table Map ->Add Table 
Map with No I nheritance and select theDEPARTMENT table (Figure 
131). 



Figure 131. Map Browser 
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□ We associate each property to an attribute of the database table. Open the 
Property M ap Editor from the context menu of the DEPARTM ENT table 
map. Click on th eMap Type in each column to select theS/'mp/emapping 
and go on to select the matching column from the database table (Figure 
132). When done, close the property map editor and the Map Browser, 



Figurel32. The Property Map Editor 


Generate the Code and Test 

Now everything is prepared to generate the code: 

□ Right-click on the EJ B group ITSO_EJ Bs and select Generates Deployed 
Code 

□ Right-click on the EJ B group ITSO_EJ Bs and select Generate ->Test 
Client 

As a result the Types pane now shows more classes. 

Totest an enterprise bean VisualAge for J ava contains a basic EJ B server. To 
add the enterprise bean to the EJ B server, right-click on the/ TSO_EJ BsEJ B 
group and select Add To -> Server Configuration (Figure 133). 
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Figure 133. E] B Server Configuration Dialog 

Starting the EJB Server in the Test Environment 

N ow we have to start each of the services: 

□ Start the Location Service Daemon. Right-click on it and select Start 
Server. 

□ Next start the Persistent Name Server the same way. 

□ Before you start the EJ B server itself, ensure that the properties are 
correct. Right-click on theEJ B Server and select Properties. Make sure 
the database URL (jdbc:db2:itsowdb ), user ID ( ITSO ) and password (itso) 
are correct (Figure 134). 


[O] Properties for EJB Server (... E3 



Database URL: |jdbc:db2:itsowdb 


Database User ID: |ITSQ 
Database Password: |““ 
LSD Name: jlocalhost 


LSD Port: [9000 


OK 


Cancel 


Figure 134. EJ B Server Properties 
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□ Finally start the EJ B server. The console should display all theservers as 
shown in Figure 135. Theserver is now ready and the enterprise bean is 
deployed in the test environment. 



Figure 135. EJ S ConsdeOutput 

Wait for all theservers to be ready before continuing with testing. 


Using the Test Client 

Now we can test the enterprise bean with the test client we generated a few 
steps earlier. 

□ Select the Department EJ B intheEy B Server Configuration Window and 
click on thefiun Test Client button (the yellow running man icon in Figure 
133) to open the test client window. 

The test client window is the same for all enterprise beans (Figure 136). 
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Figure 136. Test Client 


□ Click the Connect Button and thetest client presents the home interface 
of our department bean (Figure 137). This is only used to find or create an 
instance of the department enterprise bean. 



Figure 137. T he Fiome Interface 
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□ Now we retrieve a department with a given primary key: 

• Select the findByPrimaryKe y entry in the list of methods on the left 
side. 

• Click on the New button in the parameters list on the right side. 

• Select new DepartmentKey(Stri ng) in the constructors pane and enter 
a department number (for example, E21) as the parameter in the 
DepartmentKey dialog (Figure 138). 

• Click on the Send button and then on the Done button. 



Figure 138. Parameter Specification for the DepartmentKey 

□ Back in th e Home Interface Dialog (Figure 137) click theSand button and 
the H ome I n ter face should change to the R emote Interface, which 
represents the remote interface for the actual business logic. 

• You may now execute the methods of the enterprise bean; for example, 
to retrieve the department name, select the getDeptN a me method and 
click the Send button (Figure 139). 

• You can use the setXxxxx methods to change the values in the 
department bean retrieved. Each Send of a set method changes the 
column value in the table. (You can open a DB2 command window to 
verify the changes in the table.) 
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Figure 139. Test Client Presenting th e Remote I nterf ace 

□ You may now play around with thetest client. For instance, you might 
create a new DqaartmentBean using the home interface, and use the 
setXxxx methods to set the properties and therefore the column values in 
the department table. 

Note that the Send key for the create(DepartmentKey) method returns 
with an error message from DB2: 

com. i bm. ejs . contai ner .Contai nerExcepti on : 

com.i bm. ejs .persi stence. EJSPersi stenceException : 

C0M.ibm.db2.jdbc.app.DB2Exception: [IBM] [CLI Driver] [DB2/NT] 

SQL0407N Assignment of a NULL value to a NOT NULL column "" is not allowed. 
SQLSTATE=23502 

The columns DEPTNAME and ADMRDEPT weredefined as not null. We 
have to provide initial values. We can change the create(DepartmentKe/) 
method in the EJ B Workbench pane to set default values for the required 
fields: 

public void ejbCreate(DepartmentKey key) { 

// All CMP fields should be intialized here. 
deptNo = key.deptNo; 

deptName = "Unknown"; 
admrDept = " 

} 

With this change the creation of a new department works. The 
department name and the other fields (columns) can be changed 
afterwards using the set methods. 
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Deploy the Enterprise Bean to WebSphere 

The next step is to extract the enterprise bean and take it into a real 
environment, which is the WebSphere Application Server. WebSphere 
provides an infrastructure to run a container-managed persistence entity 
bean coded according the Sun's EJ B specification. 

Todeploya bean within the WebSphere Application Server, perform the 
following steps: 

□ First, export a J AR file containing the bean. You have two choices here: 

• Oneway is to export an already deployed version of the bean. 
VisualAgefor J ava can dothisfor you. The advantage of this method is 
that WebSphere keeps the mapping from the bean properties to the 
table attributes. 

To export thej AR file, right-click on the department EJ B in the EJ Bs 
pane and select Export ->EJ S J ar. You should pi ace the resulting J AR 
file in the deployableEJ Bs directory of WebSphere (for example, 
c: \UebSphere\AppServer\deployableEJBs\DepartmentEJS .jar). 

• The other way is to export just the bean code and let WebSphere do the 
deployment process. But this has the effect that the mapping which we 
have just done will be lost. During thedeployment process, WebSphere 
will try to create a new schema and a new table in the schema, which 
reflects the properties of the bean. If we had started from scratch, this 
method might be fine, but because we already have some data in our 
database, this is not appropriate. 

Export thej AR file (Export -> Export EJ B J ar) and WebSphere will do 
the main part of the deployment process. 

□ The next step is to generate a new EJ B container in WebSphere. This 
container holds thedatabase specification: URL, user ID, and password. If 
WebSphere supports other database systems for container-managed 
beans this might be the place where you must also specify the driver. But 
because WebSphere currently only supports DB2, we do not have to 
provide a driver. 

To create a new container, open the WebSphere administration applet. Go 
to the Enterprise] ava Services -> Global Settings. Makesure EJ S is 
enabled and the host name matches your machine name (Figure 140). If 
you us elocalhost, later on you will not be able to access the EJ B remotely. 
Apparently the naming service on the machine running the EJ B server 
differentiates between local host and servername. 
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Figure 140. WebSphere General EJ B Settings 

□ In the Containers section add a new container with the name 
ITSOContainer. Select the container and provide the specification: 

• Because we have written an entity bean, we will use the 
com.ibm.ejs.container.EJ SEntityContainer class. This is one of two 
container classes which WebSphere provides. The other container 
class, which is for session beans, is accordingly named 

com.i bm.ejs.contai ner.EJ SSessionContainer. 

• Next we have to specify the J DBC URL:j ' dbc:db2:itsowdb. 

• The directory in which to put the deployed beans is deployedEJ Bs. 

• Finally, specify the user ID and password ( ITSO and itso). 

At the bottom of this pane, you will notice a list box that shows the beans 
that are already deployed in the selected container. Because we havejust 
created a new container, no beans are listed here. 

Click on Save to preserve the changes (Figure 141). 
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Figure 141. WebSphere Container EJ B Sitings 

□ Now we are ready to deploy the bean. I n theEy B J ar Files pane (Figure 
142), select the DepartmentEJ S.jar on the left and click the Deploy button. 


WebSphere Application server] r EJB j ar F j| e information and Deployment 
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Figurel42. EJ B J ar FilePane 

□ I n the Deploy J ar F/7e dialog, select the ITSOContainer from the 
combobox and click on Deploy (this dialog is not shown). 
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□ WebSphere should now present a dialog box, warning you that the 
deployment was already done (Figure 143). Do not regenerate the jar file, 
only redeploy it (click on Redeploy Existing). If you regenerate, WebSphere 
will loose the mapping from the bean properties to the database table and 
will create a new schema and table, which is not what we want to happen. 



Figure 143. Redeployment Warning 

□ You should receive a message that the Department bean was deployed 
successfully. 

□ To make the bean available, it is necessary to restart WebSphere. Stop the 
WebSphere Servlet Service and the IBM HTTP Server and restart the 
HTTP Server (which in turn should start up WebSphere as well). 

Notice 

WebSphere will not start the EJ B services properly if there are any entity 
containers that are invalid in terms of using a non-existent or 
non-accessible database. For example, if you did not reate the sample 
database from DB2, then the deFaultEntityContainer will not beableto 
start because the database it uses is not there. In case of such a failure, 
WebSphere apparently does not start up the services at all. 

The simplest and safest solution is to remove all unused 
containers. Do this by inspecting all containersin respect to the 
deployed beans they contain. 


□ You can test the deployed bean by using the test client from Visual Age for 
J ava. After starting the test client, connect to the bean using the URL: 

i iop://hostname:9019 
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Access the Department Bean from a Servlet 

Now that our bean is deployed, how can we access it? I n our first example, we 
access the enterprise bean through a servlet. This servlet is very simple and 
contains nothing exciting except for the methods to create or find our 
enterprise bean. The servlet enables the user to retrieve a bean and to show 
and update its properties. 

The servlet ( DepartmentEJ BServlet class in itso.wasdb.ejb. servlet package) 
contains the following methods: 

□ doPost and dcGet: Both methods just call the performTask method. This 
makes the servlet independent of the selected HTTP method to transfer 
theform data. We will not list these methods here, instead refer to Figure 
85 on page 101. 

□ performTask: Based on the request, this method directs theflow either to 
the getDepartment method or the updateDepartment method. 

□ getParameter: This is a simple helper method to retrieve a parameter from 
an HTTP request object. See Figure 84 on page 100. 

□ init: This initializes theservlet. This method contains the code to start a 
connection totheEJ B server. 

□ createOrtF i ndDepartment: Based on a given key, this method tries to find 
a department; and if that department does not exist, it creates a new one. 

□ getDepartment: This method retrieves a department bean and present its 
contents in an HTM L form that enables the user to update the bean. It 
also attaches the bean to the session for usage in the next interaction. 

□ updateDepartment: This method performs the update of the contents of 
the bean. Based on theform data, it uses the setter methods of the bean 
that was retrieved in the getDepartment method. 


Class Declaration 

The DepartmentEJ BServlet'sc lass declaration is shown in Figure 144. It 
contains two class variables: 

□ The departmentH ome Variable represents the home interface of the 
DepartmentBean 

□ The initContext represents the initial context of the naming service. This 
makes it possibleto retrieve the home interface of the department bean. 
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package itso.wasdb.ejb. servlet; 

import javax.servl et.http.*; 
import javax.servl et.*; 
import itso.wasdb.ejb.*; 

public class DepartmentEJBServl et extends HttpServlet { 

DepartmentHome departmentHome = null; 

Ini ti al Context initContext = null; 


Figure 144. DepartmentEJ BSarvidc Class Declaration 


Perform Task Method 

The performTask method is simple. Depending on the request, it calls either 
the getDepartment or the updateDepartment method (Figure 145). 


public void performTask(HttpServletRequest request, HttpServl etResponse response) 

throws Servl etExcepti on, java. io. IOExcepti on { 

String command = getParameter(request, "command"); 

if ( command == null || command. equal s ("getDepartment") ) 
getDepartment(request, response) ; 
else if (command. equals("updateDepartment")) 
updateDepartment(request, response) ; 

// else print some error message ... 

} 


Figure 145. DepartmentEJ BServidt performTask Method 


Initialization 

The /n/'t method (Figure 146) initializes the servlet. It retrieves the initial 
context, which provides a starting point for naming and directory operations. 
Once we have this initial context, we can use it to look up other contexts and 
objects. This is done in the next few lines of code. 

The initial context is used to look up an object that is registered under the 
nam e Department. Using a static helper method from the generated code, 
this object is then cast to an object of type DepartmentHome, which is the 
home interface of the department bean and serves for creating and finding of 
a department enterprise bean. The resulting object is stored in the 
departmen tH ome cl ass va r i a bl e . 
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public void init(ServletConfig config) throws ServletException { 
super. init(config) ; 

System. out. pri ntl n ("Retrieving initial context..."); 
java.uti 1 .Hashtabl e properties = new java.uti 1 .Hashtabl e (2 ) ; 

// local name server 

// comment next line to run within VA Java 

properties . put ( javax . nami ng . Context . PROVIDERJJRL, "i i op : //sonoma : 9019") ; 

// IBM name services 

properti es . put (Context . INITIAL_C0NTEXT_FACT0RY , 

"com. ibm. jndi .CosNami ng.CNInitial Con text Factory") ; 

try { 

initContext = new InitialContext(properties) ; 

Object obj; 

// lookup the home interface using the JNDI name 
System. out. pri ntl n ("Retrieving the home interface..."); 

Object o = initContext.lookup("Department") ; // this is the JNDI name 
if (o instanceof org.omg.CORBA. Object) 

departmentHome = DepartmentHomeHelper.narrow((org.omg.CORBA. Object) o) ; 
System. out. pri ntl n ("Creati ng DepartmentHome. . . ") ; 

} catch (NamingException e) { 

throw new Servl etExcepti on (e. toStri ng () ) ; 

} 

} 


Figurel46. DepartmentE] BServlA init M dihod 


Retrieve a Department Bean 

The next method to look at is the gdtDepartment method that uses the home 
interface to either create a new enterprise bean or find an already existing 
bean based on the primary key given in the HTTP request (Figure 147). 

We do not describe the method in detail, but will concentrate on the 
interesting parts that are marked in bold face. 
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public void getDepartment(HttpServl etRequest request, HttpServl etResponse response) 

throws Servl etExcepti on, java. i o. IOExcepti on { 

response. setContentType("text/html ") ; 
response. setHeader("Pragma" , "no-cache") ; 
response. setHeader("Cache-Control ", "no-cache") ; 
response. setDateHeader("Expires" , 0) ; 

// Get the output writer 

java.io.PrintWriter out = response. getWri ter() ; 

// Get the deptNo to look for 

String deptNo = getParameter(request, "deptNo"); 

out .printl n ("<HTML><HEAD><TITLE>DepartmentEJBServl et </TITLE></HEAD><BODY>") ; 
try { 

Department dep = createOrFindDepartment(deptNo) ; 

out.println("<TABLE> <F0RM ACTION" + 

"= \" /servl et/i t so. was db.ejb. servl et . Department EJBServl et\">") ; 

out.println("<TR>") ; 
out.println("<TH>Department Number") ; 
out.println("<TH>Department Name") ; 
out.println("<TH>Department Location") ; 
out.println("<TH>Admr. Department") ; 
out.println("<TH>Manager Number") ; 

out.println("<TR><TD>" + deptNo); 

out. printing" <TD><INPUT TYPE=TEXT NAME=deptName VALUE=\"" + 
dep.getDeptName() + "\">"); 

out.println(" <TD><INPUT TYPE=TEXT NAME=1 ocati on VALUE=\"" + 
dep.getLocation() + "\">"); 

out.printlnf" <TD><INPUT TYPE=TEXT NAME=admrDept VALUE=\"" + 
dep.getAdmrDept() + "\">"); 

out.println(" <TD><INPUT TYPE=TEXT NAME=mgrNo VALUE=\"" + 
dep.getMgrNo() + "\">"); 

out.println("<TR><TD><INPUT TYPE=HIDDEN NAME=command VALUE=updateDepartment>") ; 
out.println("<TD><INPUT VALUE=Update TYPE=SUBMIT>") ; 
out . pri nt 1 n ( "</ F0RM></TABLE>" ) ; 

HttpSession session = request. getSession(true) ; 

session.putValue("itso.wasdb.ejb.servlet.DepartmentEJBServlet. department", 
dep); 

} catch (Exception e) { 

out.println("<h2>Error: " + e + " </h2> " ) ; 
e.printStackTrace(out) ; 

} 

out.println("</BODY></HTML>") ; 


Figure 147. DepartmentEJ bSarv! A gAD apartment M dihod 
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The first poi nt of i nterest is where the actual enterprise bean is obtained. 
This is done by the createOrF i ndDepartment method based on a primary key 
given in the HTTP request. The contents of this bean are then presented in 
an HTM L form. 

This leads tothe next interesting point: The bean itself is attached tothe 
current HTTP session for later usage in the updateDepartment method. 


Create or Find a Department Bean 

Now let us inspect the createOrF i ndDepartment method (Figure 148). This 
method tries to find an enterprise bean, and if it cannot find one, it creates a 
new enterprise bean. Both operations utilize the home interface of the 
department bean. I n any case, it will return the bean tothecaller. 


public Department createOrFindDepartment(String key) throws NamingException, 

ObjectNotFoundException, RemoteExcepti on, CreateExcepti on { 

Department dep = null; 
try { 

dep = departmentHome.fi ndByPrimaryKey (new DepartmentKey (key) ) ; 

} catch (javax.ejb.FinderException e) { 

System. out. pri ntl n ("Department not found! Create new one"); 
dep = departmentHome.create(new DepartmentKey(key) ) ; 

} 

return dep; 

} 


Figurel48. DepartmentE J BServId: createOrF i ndDepartment Method 


Update the Department Bean 

The last method that is important for our servlet is the updateDepartment 
method (Figure 149). The interesting parts are again shown in bold face. 

Basically, the session that was created in the getDepartment method is used 
to retrieve the attached department bean. Then, based on the form data, it 
follows a simple sequence of setXxxx invocations of the department bean. 
That is the update! 
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public void updateDepartment(HttpServl etRequest request, HttpServl etResponse response) 
throws ServletException, java.io.IOException { 
response. setContentType("text/html ") ; 
response. setHeader("Pragma" , "no-cache") ; 
response. setHeader("Cache-Control ", "no-cache") ; 
response. setDateHeader("Expires" , 0) ; 

java.io.PrintWriter out = response. getWri ter() ; 

out .printl n ("<HTML><HEAD><TITLE>Resul t</TITLE></HEAD><BODY>") ; 

HttpSession session = request. getSession(false) ; 

Department dep = (Department) 

session.getValue("itso.wasdb.ejb.servlet.DepartmentEJBServlet. department") ; 

String location = getParameter(request, "location"); 

String admrDept = getParameter(request, "admrDept"); 

String mgrNo = getParameter(request, "mgrNo"); 

String deptName = getParameter(request, "deptName"); 

dep. set Location (location) ; 
dep . setAdmrDept (admrDept) ; 
dep . setMgrNo (mgrNo) ; 
dep. setDept Name (dept Name) ; 

out.println("<Hl>Update ok</Hl>") ; 
out.println("</BODY></HTML>") ; 


Figure 149. DepartmentE J BServId: updatdDepartment M dchod 


Test the Servlet in VisualAge for Java 

Start the WebSphere Test Environment (SE Runner class) and make sure 
that the EJ B server is running (see "Generate the Code and Test" on 
page 143). 

Comment one line in the init method (Figure 146 on page 155): 

// properties. put(javax. naming. Context. PR0VIDER_URL, "i iop://sonoma:9019") ; 

I nvoke the servlet with the URL: 

http://127.0.0. 1: 8080/servlet/it so. wasdb.ejb.servl et.DepartmentEJBServl et? 
deptNo=E21 

Executing the servlet results in the browser output shown in Figure 150. 
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Test the Servlet in WebSphere 

Now let us try to invoke the servlet with the deployed enterprise bean under 
WebSphere. Export the cl ass file of the servlet from Visual Age for J ava to the 
WebSphere servlets directory: 

c:\WebSphere\AppServer\servlets\i tso\wasdb\ejb\servlet 
I nvoke the servlet with the URL: 

http://hostname/servl et/i tso.wasdb.ejb. servl et .Department EJBServl et? 
command=getDepartment&deptNo=E21 

Executing the servlet results in the browser output shown in Figure 150. 



Figure 150. DepartmentE J BServid: in a Browser 

You may now change the contents of the bean and click on Update Keep in 
mind that you should not exceed the lengths of the fields; otherwise, the 
update will not succeed. For example, th eAdmr. Department may not be 
longer than three characters. 

If the update was successful, the servlet will let you know. Click on Back to 
retrieve the enterprise bean again and verify that the bean has changed. 
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Access the Department Bean from an Application 

I n the same way that we have used a servlet to access our enterprise bean, 
we might want to use an application or an applet. We will develop a simple 
panel that works the same way our servlet does. The user can enter a 
department number; if the department exists the applet will show its 
content, if not it will create a new department bean. This panel might be 
added to an application or toan applet. 


Create the GUI Layout 

We use Visual Age for J ava to develop the applet. 

□ Create a new package called itso.wasdb.ejb.client. 

□ In this package create a new class called Department? and. Derive this 
class from the Swing J Panel class and mark the Compose the cl ass 
visually checkbox in the SmartGuide. 

□ I n the Visual Composition E ditor, design the panel . 

Thefinal panel with connections is shown in Figure 151. 
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Create the Connections 


1. First, we have to create a connection to the server to retrieve the initial 
context and the home interface of the department bean. This requires a 
method to initialize thecontext and the home interface based on the 
server name. We will use a new method called createOrFind. 

For the Create/ Find Department button, select £ vent to Code from the 
context menu and enter the createOrFind method code (Figure 152). 
Notice that the code is almost the same as for the servlet (Figure 148 on 
page 157), and again the error handling is only very rudimentary. 

2. For the parameters of the method, select the text field next to the 
Servername label and the text field next toth eCreate/ Find Department 
button. 

3. The createForFind method provides our department bean as a result. To 
be more precise, it provides an implementation of the Department 
interface. To store this object we use a variable named department and we 
use the context menu to change its type to Department. Therefore, we 
connect the normal Result of the createOrF i nd method to our department 
variable (this property). 

4. Now that department is a valid object, weconnect each property of 
department ( admrDept , location, mgrNo, and deptName) to the matching 
text properties of the text fields. 

5. For the U pdate button weconnect actionPerformed toth esetLocation 
method of department. Because the setLocati on method requires a 
parameter, we provide it with the text property of the department name 
text field. 

6. Next, we do the same for theother properties: admrDept, mgrNo, and 
deptName 
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public itso.wasdb.ejb. Department createOrFind(String key. String adress) { 

// Get the initial context 
if (initContext == null) { 
try { 

System. out. pri ntl n ("Retrieving initial context..."); 
java.uti 1 .Hashtabl e properties = new java.uti 1 .Hashtabl e (2 ) ; 

// local name server 

// comment the next line to run inside VA Java 

properties. put(javax. naming. Context. PROVIDERJJRL, "iiop://" + adress + 

// IBM name services 

properties. put (javax. naming. Context. I NITIAL_CONTEXT_FACTORY, 

"com.i bm. jndi .CosNami ng.CNIni tial Con text Factory") ; 
initContext = new javax. naming. InitialContext(properties) ; 

} catch (javax. naming. Nami ngExcepti on e) { 

System. out. pri ntl n ("Error retrieving the initial context: " + e) ; 

} // endtry 


Object obj; 

if (departmentHome == null) { 

// lookup the home interface using the JNDI name 
try { 

System. out. pri ntl n ("Retrieving the home interface..."); 

Object o = initContext.lookup("Department") ; // this is the JNDI name 
if (o instanceof org.omg.CORBA. Object) 

departmentHome = DepartmentHomeHelper.narrow((org.omg.CORBA. Object) o) ; 
el se 

System. out. pri ntl n ("Type mi smatch") ; 

} catch (javax. naming. Nami ngExcepti on e) { 

System. out. pri ntl n ("Error retrieving the home interface: " + 
e.getMessage() ) ; 

} // endtry 

} 

System. out. pri ntl n ("Creati ng Department ") ; 

Department dep = null; 
try { 

dep = departmentHome. findByPrimaryKey(new DepartmentKey (key) ) ; 

System. out. pri ntl n ("Department found! ") ; 

} 

catch (javax. ejb.ObjectNotFoundException e) { 

System. out. pri ntl n ("Department not not, create a new one"); 
try { 

dep =. departmentHome. create(new DepartmentKey(key) ) ; 

} catch (Exception excp) { 

excp.pri ntStackTrace( System. out) ; 

System. exit(l) ; 

} 

} catch (Exception e) { 

e.printStackTrace(System.out) ; 

System. exit(l) ; 

} 

return dep; 


Figure 152. DepartmentPanel createOrFind Method 
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Test the Applet or Application 

Because Visual Age for J ava automatically creates a main method for testing 
purposes, we can already test the panel. The normal way is to imbed the 
DepartmentPand in an applet or application. We do not show how this 
process is done because it is just a trivial step. However, the sample 
repository provides an applet and an application that use the 
DepartmentPand. 

To test the panel , execute it, enter your server name and a val id department 
number, and click Create/ Find Department button (Figure 153). 



Figure 153. Department Pane! Displaying the Department Bean 


Notice 

We were not able to access the department bean from an applet running 
inside a browser, although it was possible to run the applet inside a remote 
applet viewer. 

Presumably, this has something to do with the security restrictions under 
which the applet has to run inside a browser. 
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Developing a Bean Managed Persistence Entity Bean 

In this section we will develop an entity bean that manages its persistence 
itself. For this example, we will take the second tableof our sample database 
and develop a bean that stores its statetothe employee tableof thedatabase. 

We will again start with the SmartGuide of VisualAgefor J ava to create the 
bean. 


Create an Employee Enterprise Bean with the SmartGuide 

Similar to the process of adding a container managed bean, we now have to 
add another bean to our ITSO_EJ Bs group (select Add To->EJ B). 

Create a new enterprise bean, but this time select Entity Bean with Bean- 
managed Persistence (BMP) for the bean type. Name it Employee and add it 
tothe itso.wasdb.ejb package (Figure 154). 



Figure 154. Adding a BMP Bean 
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Add Properties and Methods 

Now we add the properties to the bean. This is similar to the steps we have 
done for the CM P bean, except that it is not possible to mark a property to be 
container-managed, and there is also no way to mark a property to be the 
primary key field (Figure 155). 

For each column of the employee table, create a matching property with 
getters and setters (no setter for the employee number). Add all getters and 
setter to the remote interface (Add To->EJ B Remotel nter face). 
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Figure 155. Properties in the Workspace View 

The properties are listed in Table 3. 

Table 3. Properties of the Employee Bean 


Type 

Name 

Type 

Name 

String 

empNo 

String 

firstName 

String 

midi nit 

String 

lastName 

String 

work Dept 

String 

phoneNo 

java. util. Date 

hireDate 

String 

job 

String 

sex 

java. util. Date 

birthDate 

double 

salary 

double 

bonus 

double 

comm 

short 

ed Level 

itso.wasdb.ejb. 

EmployeeStorage 

storage (private, 
no getter /setter) 
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Provide the Employee Bean with Persistence Functionality 

The only thing, apart from additional business functionality, is to provide the 
bean with the functionality that it can persist itself to some database system. 

To implement the persistence, we have to understand which methods of the 
bean are invoked bytheEJ B container and what the purpose of each method 
is. VisualAgefor J ava by default creates thefollowing methods: 

□ public void ejbLoadf): This method is invoked by the container to 
synchronize the bean according to the state represented in the database. 
This means that the enterprise bean has to be able to refresh itself from 
the table. 

□ public void ejbStoref): This is the counterpart of the ejbL oad method. 

1 1 synchronizes the database accordi ng to the state of the enterprise bean. 
The bean has to able to write its state into the database. 

□ public E mployeeKey qbFindByPri maryKey(E mployeeKeykey) : This 
method retrieves an object with a given key from the database and 
returns the key. 

□ public E mployeeKey ejbCreate(E mployeeKey key) : This method is 
invoked when the client requests a new enterprise bean using the home 
interface method create(...). This method is usually the place to validate 
the argument given from the client and to insert a new row in the 
database table that represents the contents of the enterprise bean. 

□ public void ejbRemovef): The container invokes this method to end the 
life of this enterprise bean. This is the pi ace to delete the record that 
represents this bean from the database. 

□ public void ejbActivatef ): This method is invoked when the container 
picks an instance from the pool and assigns it to a specific enterprise bean 
object. According to the EJ B specification, this is not the pi ace to read the 
state of the bean from a database; this should be done in the qbLoad 
method. The ejbActivate method gives the bean the chance to use, 
initialize, or acquire additional resources. This method is invoked by the 
container prior to the invocation of ejbL oad. 

□ public void ejbPassivatef): This is the counterpart of the ejbActivate 
method. It gives the enterprise bean the chance to release any resources 
that were acquired during the ejbActivate method. This method is called 
directly prior to the invocation of the ejbStore method. 

There are some more methods, but at the moment those are of no interest. 
We have to implement the q'bLoad, ejbStore, ejbFindByPrimaryKey, 
qbCreate, and ejbRemove methods. Because we do not use any additional 
resources, we can skip the gbAct/vate and ejbPassivate methods. 
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To make the bean persistent, we use the I BM data access beans. The usage is 
capsulated in the Employees torage cl ass. This class is responsible to create a 
new row, to retrieve a row, to update a row, or to delete a row from the 
employee table of our database. Therefore, among the attributes that 
represent the actual employee object, the EmployeeBean holds a private 
instance of an Employees torage class, named storage. 

I n the following code snippets, weonly describe how to find and update an 
entity bean and the respective database record. The actions to remove or 
create a new entity bean are very similar. 

Methods of the Entity Bean 

The code for the ejbFindByPrimaryKe y method (and for most methods of the 
entity bean) is very short and simple. The main work is done in the 
E mpl oyeeS torage cl ass. 

I n this method wecreate a new i nstance of the Employees torage (if not 
already there) and invoke the findEmployee method with the instance of the 
enterprise bean and the primary key (Figure 156). 


public EmployeeKey ejbFindByPrimaryKey (Empl oyeeKey key) 
throws javax.ejb. FinderExcepti on { 

try { 

if (storage == null) 

storage = new i tso.wasdb.ejb. Empl oyeeStorageQ ; 
this.empNo = key.primaryKey; 
storage. findEmployee(this, key.primaryKey) ; 

} catch(Exception e) { 

throw new Fi nderExcepti on(e.toString() ) ; 

} 

return key; 

} 


Figure 156. EmployeeBean ejbFindByPrimaryKey Method 

The ejbStore method to store the entity bean and synchronize its contents 
with the database is also rather simple. The only thing done here is to invoke 
the update method of thestorage class (Figure 157). 


public void ejbStore () throws java.rmi .RemoteException { 
try { 

storage. updateEmpl oyee(thi s) ; 

} catch (com.ibm.db.DataException e) { 

throw new RemoteExcepti on(e.toString() ) ; 

} 


Figure 157. EmployeeBean ejbStore Method 
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Figure 158 shows some of the other methods. 


public void ejbActivate() throws java.rmi .RemoteExcepti on { 
try { 

storage = new i tso.wasdb.ejb. Empl oyeeStorageQ ; 

} catch (Exception e) { 

throw new RemoteExcepti on(e.toString() ) ; 

} 

} 

public void ejbPassivateQ throws java.rmi .RemoteExcepti on { 
try { 

storage. close() ; 

} catch (com.ibm.db.DataException e) { 

throw new java.rmi .RemoteExcepti on(e.toStri ng() ) ; 

} 

storage = null; 

} 

public void ejbLoad() throws java.rmi .RemoteExcepti on { 
if (storage == nul 1) 

throw new RemoteException("Storage not initialized"); 
try { 

storage. findEmployee(this, empNo) ; 

} catch (com.ibm.db.DataException e) { 

throw new RemoteExcepti on(e.toString() ) ; 

} 

} 

public void ejbRemove() throws java.rmi .RemoteExcepti on { 
try { 

storage. del eteEmpl oyee( empNo) ; 

} catch (com.ibm.db.DataException e) { 

throw new RemoteExcepti on(e.toString() ) ; 



public EmployeeKey ejbCreate(EmployeeKey key. String firstName, String midinit. 

String lastName, String workDept, String phoneNo, java. uti 1 .Date hireDate, 
String job, short edLevel , String sex, java. util .Date birthDate, double salary, 
double bonus, double comm) throws CreateExcepti on { 
this. empNo = key.primaryKey; 

this. firstName = firstName; this. lastName = lastName; this. midinit = midinit; 
this. edLevel = edLevel; this. workDept = workDept; this. phoneNo = phoneNo; 
this. hireDate = hireDate; this. job = job; this. sex = sex; this. comm = comm; 
this. birthDate = birthDate; this. salary = salary; this. bonus = bonus; 
try { 

if (storage == null) storage = new itso.wasdb.ejb.EmployeeStorage() ; 
storage. createEmpl oyee(thi s) ; 

} catch(Exception e) { 

throw new CreateException(e.toStringO) ; 

} 

return key; 


F i gure 158. E mpl oyeeB ean M &hods 
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The EmployeeStorage Class 

Now we implement the Employees toragedass, and specifically, thetwo 
methods of the storage cl ass that were used i n the two methods of the entity 
bean, namely the findEmployee method and the updateEmployee method. 

Class Declaration 

We start with the declaration of the class (Figure 159). 


package itso.wasdb.ejb; 


import java. sql .Connection; 
import java. sql .Types; 
import com.ibm.db.*; 
import java. uti 1 .Date; 
import java. uti 1 .Cal endar; 
import java. math. BigDecimal ; 


public class EmployeeStorage { 


static int database 
final static String 
final static String 
/* 

static int database 
final static String 
final static String 
static int database 
final static String 
final static String 
*/ 

final static String 
final static String 


= 1; // DB2 

URL = " jdbc: db2 : i tsowdb" ; 

DRIVERNAME = "COM. i bm.db2. j dbc .app. DB2Dri ver" ; 

= 2; // Oracle 

URL = " jdbcroracl e:thin :@sonoma: 1521 :orcl" ; 
DRIVERNAME = "oracl e. jdbc. dri ver .Oracl eDri ver" ; 
= 3; // SQL Server 

URL = "jdbc; odbc : Sql Server" ; 

DRIVERNAME = "sun .jdbc. odbc .JdbcOdbcDri ver" ; 


USER = "ITSO"; 
PASSWORD = "itso"; 


static String SELECT = 

"SELECT EMPNO, FIRSTNME, MIDINIT, LASTNAME, WORKDEPT, PHONENO, " + 

"JOB, SEX, SALARY, BONUS, COMM, HIREDATE, BIRTHDATE, EDLEVEL " + 

"FROM ITSO. EMPLOYEE WHERE EMPLOYEE. EMPNO = : EMPNO"; 
final static String INSERT = 

"INSERT INTO ITSO . EMPLOYEE VALUES (:EMPN0, : FIRSTNME, :MIDINIT, ; LASTNAME, 

:W0RKDEPT, : PHONENO, : JOB, : SEX, : SALARY, : BONUS, :C0MM, iHIREDATE, :BIRTHDATE, 
: EDLEVEL)"; 

final static String DELETE = 

"DELETE FROM ITSO. EMPLOYEE WHERE EMPNO = : EMPNO"; 


static StatementMetaData sel ectMetaData = null; 

static StatementMetaData i nsertMetaData = null; 

static StatementMetaData del eteMetaData = null; 

static DatabaseConnecti on dbConn = null; 
SelectResult resultSet = null; 

} 


Figure 159. E mployeeStorageClass Declaration 
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The E mpl oyeeStorage cl ass defi nes the database that wi 1 1 be used, the user 
I D, and the password. It also contains static references to the different SQL 
statements: select, insert and delete. The actual statements will be created 
later, we only define thestring constants here. Notice that no update string is 
defined. The update is done through the data access bean. We do not have to 
define anything for this. At the very bottom we define a nonstatic 
SelectResult. This result will be used to update a row fetched from the 
database. 

This example uses the DB2 database, but we could have used any other 
database that provides the ITSOWDB database as well, although the code 
differs a little bit (see "Different Mapping of SQL Types" on page 264). 

Initializing the Meta Data 

The next method we describe is the method that initializes the meta data for 
the select statement. This method is static because the actual select 
statement is the same and independent of specific instances of the entity 
bean (Figure 160). 


stati c 
sel 
sel 
// 
sel 
// 
sel 
sel 
sel 
sel 
sel 
sel 
sel 
sel 


void initSel 

ectMetaData 

ectMetaData. 

Use the defa 

ectMetaData. 

Next define 

ectMetaData. 

ectMetaData. 

ectMetaData. 

ectMetaData. 

ectMetaData. 

ectMetaData. 

ectMetaData. 

ectMetaData. 


ect() throws DataExcepti on { 

= new StatementMetaData() ; 
setSQL(SELECT) ; 

ult mapping, Oracle seems to have problems 
addParameter("EMPNO" , Stri ng.cl ass , Types 
all ouput parameter in the same way 
Stri ng.cl ass , 


addCol umn ("EMPNO" , 
addCol umn("FIRSTNME" , 
addCol umn ("MIDI NIT" , 
addCol umn ("LASTNAME" , 
addCol umn("WORKDEPT", 
addCol umn ("PHONENO" , 
addCol umn ("JOB" , 
addCol umn ("SEX" , 


Stri ng.cl ass , 
Stri ng.cl ass , 
Stri ng.cl ass , 
Stri ng.cl ass , 
Stri ng.cl ass , 
Stri ng.cl ass , 
Stri ng.cl ass , 


Types 

Types 

Types 

Types 

Types 

Types 

Types 

Types 


otherwi se 
.CHAR) ; 

.CHAR) ; 
.VARCHAR) ; 
.CHAR) ; 
.VARCHAR) ; 
.CHAR) ; 
.CHAR) ; 
.CHAR) ; 
.CHAR) ; 


if (database == 1) { //DB2 

sel ectMetaData. addCol umn ("SALARY" , Doubl e.cl ass, 
sel ectMetaData. addCol umn ("BONUS" , Doubl e.cl ass , 
sel ectMetaData. addCol umn ("COMM" , Doubl e.cl ass , 
sel ectMetaData. addCol umn ("HIREDATE" , Types .DATE, 
sel ectMetaData. addCol umn ("BIRTHDATE" , Types .DATE, 
sel ectMetaData. addCol umn ("EDLEVEL" , Short .cl ass , 


Types. DECIMAL); 
Types. DECIMAL); 
Types. DECIMAL); 
Types. DATE) ; 
Types. DATE) ; 
Types. SMALLINT); 


else if (database == 2) { //Oracle 

sel ectMetaData. addCol umn ("SALARY" , Types . DECIMAL, Types .DECIMAL) ; 


} 

// Define the table name which is used in the query 
sel ectMetaData. addTable("ITSO. EMPLOYEE") ; 


F i gure 160. Initialize the Select 5 tatemen t 
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The code of this method is specific for DB2, because Oracle and the SQL 
Server differ in they way they map SQL types (see "Different Mapping of 
SQL T ypes" on page 264). Due to that, we had to use different specifications 
for the meta data for the different databases. The sample code of this class 
contains the code for all three database systems. 

Constructor 

The constructor calls the initialize method to set up a database connection 
and the meta data for the select, insert, and delete statements (Figure 161). 


public Empl oyeeStorage() throws DataExcepti on { 
super() ; 
ini ti al i ze() ; 

} 

private void initialize() throws DataExceptionf 
// user code begin {1} 
i f (dbConn == null) { 
initConnection() ; 
initSelect() ; 
initlnsert() ; 
initDelete() ; 

} 

// user code end 
// user code begin {2} 

// user code end 

} 


Figure 161. E mployeeBean ejbStoreM dihod 

The initDelete and initl nsert methods are similar to the initS elect method. 

Find an Employee 

As we saw in Figure 156 on page 167 the qbFindByPri maryK ey method used 
the findE mployee method of the Employees torageti ass. This method uses the 
meta data for the select statement, which was initialized in th einitSelect 
method. 

The findE mployee method is rather simple: A new SelectStatment is created 
which uses the database connection and the prepared meta data to run a 
query against the database. If a row was found, the employee bean is filled 
with the column contents of that row (Figure 162). 

Notice that the method does not close the resultSet, and that this resultSet is 
an instance variable of the cl ass. 
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public void findEmployee(EmployeeBean empl , String key) 

throws java.rmi .RemoteException, DataExcepti on { 

Sel ectStatement select = new Sel ectStatement() ; 

sel ect .setConnecti on (dbConn) ; 

sel ect .setMetaData(sel ectMetaData) ; 

// Now set the Paramenter for the query 
sel ect.setParameter("EMPNO" , key) ; 

// and execute the query 
sel ect.executeO ; 

// Retrieve the result set 
resultSet = sel ect.getResul t() ; 
if (resul tSet.getNumRows () == 0) 

throw new java.rmi .RemoteException("No Record found"); 

// Now get the resulting column by name 

empl . set Firs tName (resul tSet .getCol umnVal ueToString ("FIRSTNME") ) ; 
empl .setMidlni t (resul tSet.getCol umnVal ueToStri ng("MIDINIT") ) ; 
empl . set Las tName (resul tSet.getCol umnVal ueToStri ng("LASTNAME") ) ; 
empl . setWorkDept (resul tSet .get Col umnVal ueToStri ng ("WORKDEPT") ) ; 
empl . setPhoneNo (resul tSet.getCol umnVal ueToStri ng("PH0NEN0") ) ; 
empl .set Job (resul tSet.getCol umnVal ueToString ("JOB") ) ; 
empl .set Sex (resul tSet.getCol umnVal ueToString ("SEX") ) ; 
empl .set Hi reDate( (Date) resul tSet.getCol umnVal ue("HIREDATE") ) ; 
empl .setBi rthDate( (Date) resul tSet.getCol umnVal ue("BIRTHDATE") ) ; 
if (database =w 1) { //DB2 

empl .set Sal ary ( ( (Doubl e) resul tSet.getCol umnVal ue( "SALARY") ) .doubl eVal ue() ) ; 
empl .set Bonus ( ( (Doubl e) resul tSet.getCol umnVal ue(" BONUS" ) ) .doubl eVal ue() ) ; 
empl . set Comm ( ( (Doubl e) resul tSet.getCol umnVal ue("C0MM")) .doubl eVal ue ( ) ) ; 
empl .setEdLevel (( (Short) resul tSet.getCol umnVal ue("EDLEVEL") ) . shortVal ue() ) ; 


else if (database == 2) { //Oracle 

empl .set Sal ary ( ((BigDecimal ) resul tSet.getCol umnVal ue ( "SALARY" ) ) . 
doubl eVal ue()) ; 

empl . set Bonus ( ( (Bi gDecimal ) resul tSet.getCol umnVal ue( "BONUS")) .doubl eVal ue() ) ; 
empl . set Comm (( (Bi gDecimal ) resul tSet.getCol umnVal ue(" COMM") ) .doubl eVal ue() ) ; 
empl .setEdLevel (( (Bi gDecimal ) resul tSet.getCol umnVal ue("EDLEVEL") ) . 
shortVal ue() ) ; 


Figure 162. Find an E mployee 


Update an Employee 

The updateE mployee method changes a record in thedatabase based on the 
data in the employee bean. This method uses the resultSet that was assigned 
in the findE mployee method. This makes the updatestep quite simple 
(Figure 163). 

Based on the resultSet from the find Employee method, the new values for the 
row are set from the bean. Finally, theresultSet is updated. The resul tSet ls 
not closed in the updateE mployee method; it is closed when the container 
invokes the ejbPassivate method, which cal Is the dose method of the 
E mpl oyeeS tor age cl ass. 
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The method uses a small date2Timestamp method that converts a 
java. util. Date object to a java.sql. Timestamp object that is required by 
Oracle. This code is specific to the Oracle database. 


public void updateEmployee(EmployeeBean empl) throws DataExcepti on { 
resul tSet .setCol umnVal ue("FIRSTNME" , empl .getFi rstName() ) ; 
resul tSet .setCol umnVal ue( "MIDI NIT" , empl .getMidlni t () ) ; 
resul t Set .setCol umnVal ue("LASTNAME" , empl . get Last Name () ) ; 
resul t Set .setCol umnVal ue("WORKDEPT" , empl .getWorkDept ()) ; 
resul t Set .setCol umnVal ue("PH0NEN0" , empl .getPhoneNo() ) ; 
resul t Set .setCol umnVal ue(" JOB" , empl .get Job ()) ; 
resul t Set .setCol umnVal ue(" SEX" , empl ,getSex() ) ; 
resul t Set .setCol umnVal ue(" SALARY" , new Doubl e(empl .getSal ary() ) ) ; 
resul t Set .setCol umnVal ue(" BONUS" , new Doubl e (empl .get Bonus () ) ) ; 
resul tSet. setCol umnVal ue("C0MM" , new Doubl e(empl .getComm() )) ; 

if (database == 1) { //DB2 

Calendar cal = Cal endar.getlnstance() ; 
cal .setTime(empl .getHi reDate() ) ; 
java.sql .Date hireDate = 

new java.sql .Date(cal .get(Cal endar. YEAR) - 1900, 

cal .get (Cal endar. MONTH) , cal .get (Cal endar .DAY_0F_M0NTH) ) ; 
resul t Set .setCol umnVal ue ("HIREDATE" , hireDate) ; 
cal .setTime(empl .getBirthDateO) ; 
java.sql .Date birthDate = 

new java.sql .Date(cal .get(Cal endar. YEAR) - 1900, 

cal .get (Cal endar. MONTH) , cal .get (Cal endar. DAY_0F_M0NTH) ) ; 
resul t Set .setCol umnVal ue(" BIRTHDATE" , bi rthDate) ; 
resul t Set .setCol umnVal ue("EDLEVEL" , new Short (empl .get Ed Level () ) ) ; 
} else if (database == 2) { //Oracle 
resul t Set .setCol umnVal ue ("HIREDATE" , 
date2Timestamp(empl ,getHireDate())) ; 
resul t Set .setCol umnVal ue(" BIRTHDATE" , 
da te2Times tamp (empl .getBi rthDate () ) ) ; 
resul t Set .setCol umnVal ue("EDLEVEL" , 

new Bi gDecimal (Integer. toStri ng(empl .getEdLevel ()))); 

} 

resul tSet.updateRow() ; 


Figure 163. Update the Database 


Delete an Employee 

The deleteE mployee method removes the database record with a given key. 

public void deleteEmployee(String key) throws DataException { 

SQLStatement delete = new SQLStatement() ; 

del ete.setConnecti on (dbConn) ; 

del ete.setMetaData (del eteMetaData) ; 

// Now set the Parameters for the delete 
del ete.setParameter("EMPNO" , key) ; 
del ete.execute() ; 
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Testing the Employee Bean 

Before testing theemployee bean, you have to generate the home and helper 
classes. Sel ect E) Bs -> Generates Deployed Code for the employee 
enterprise bean. 

Start the EJB Server 

Add the ITSO_EJ Bstotheserver (Add To -> Server Configuration) and start 
the server (see "Starting the EJ B Server in theTest Environment” on 
page 144). Be sure to verify the properties of the server before starting it (see 
Figure 134 on page 144). 

Test Client 

You can use the test client against the employee bean and retrieve an 
employee and update its properties. Generate the test client code (select 
Generate ->Test Client) and start it (see "Using theTest Client" on page 145). 


Access the Employee Bean from a Servlet 

For the employee enterprise bean wecreated a servlet ( EmployeeEJ BServlet) 

that accesses the employee enterprise bean. 

The structure of the servlet is exactly the same as the DepartmentEJ BServlet 

described in "Access the Department Bean from a Servlet" on page 153, 

therefore we do not list the complete implementation here. 

The servlet consists of the foil owing methods: 

□ init initializes the context and determines the home interface of the 
employee bean. 

□ doGet and doPost, which both call the per for mTask method. 

□ performTask decides whether an employee should be retrieved (invoke 
getEmployee) or updated (invoke updateE mployee). 

□ findE mployee retrieves an employee bean based on the employee number 
by using the home interface of theemployee bean. 

□ getEmployee uses findE mployeeto retrieve the employee bean and display 
it (partially) in an F)TM L form (Figure 164). 
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public void getEmployee(HttpServletRequest request, HttpServl etResponse response) 
throws Servl etExcepti on, java. io. IOExcepti on { 
response. setContentType("text/html ") ; 
response. setHeader("Pragma" , "no-cache") ; 
response. setHeader("Cache-Control ", "no-cache") ; 
response. setDateHeader(" Exp i res" , 0) ; 

// Get the output writer 

java.io.PrintWriter out = response. getWri ter() ; 

String empNo = getParameter(request, "empNo"); 

out .pri ntl n ( "<HTML><HEAD><TITLE>Empl oyeeEJBServl et </TITLE></HEAD><BODY>") ; 
try { 

Employee emp = fi ndEmployee (empNo) ; 

out.println("<TABLE>" + 

"<F0RM ACTION = \"/servl et/i tso.wasdb . ej b .servl et . Empl oyeeEJBServl et\">") ; 
out.println("<TR>") ; 
out .pri ntl n ("<TH>Empl oyee No") ; 
out.println("<TH>Firstname") ; 
out.println("<TH>Midinit") ; 
out.println("<TH>Lastname") ; 
out.println("<TH>Phone") ; 
out .pri ntl n ("<TH>Sal ary") ; 
out.println("<TR><TD>" + empNo); 

out. printing" <TD><INPUT TYPE=TEXT NAME=f i rstName VALUE=\"" + 
emp.getFirstName() + "\">"); 

out.println(" <TD><INPUT SIZE=1 TYPE=TEXT NAME=midinit VALUE=\"" + 
emp.getMidInit() + "\">"); 

out.println(" <TD><INPUT TYPE=TEXT NAME=1 astName VALUE=\"" + 
emp.getLastName() + "\">"); 

out.println(" <TD><INPUT SIZE=4 TYPE=TEXT NAME=phoneNo VALUE=\"" + 
emp.getPhoneNo() + "\">"); 

out.printlnf" <TD><INPUT SIZE=11 TYPE=TEXT NAME=salary VALUE=\"" + 
emp.getSalaryO + "\">"); 

out.println("<TR><TD><INPUT TYPE=HIDDEN NAME=command VALUE=updateEmployee>") ; 
out.println("<TD><INPUT VALUE=Update TYPE=SUBMIT>") ; 
out . pri nt 1 n ( "</ F0RM></TABLE>" ) ; 

HttpSession session = request. getSession(true) ; 

sessi on.putVal ue("i tso.wasdb. ejb. servl et. Empl oyeeEJBServl et. empl oyee" , emp) ; 

} catch (Exception e) { 

out.println("<h2>Error: " + e + " </h2> " ) ; 
e.printStackTrace(out) ; 

} 

out.println("</BODY></HTML>") ; 


public Employee findEmployee(String key) 

throws NamingException, ObjectNotFoundExcepti on, RemoteException, FinderException { 
Employee emp = null; 

emp = employeeHome.findByPrimaryKey(new Empl oyeeKey(key) ) ; 
return emp; 


Figure 164. RAri&/eand Display the Employee Bean 
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□ updateE mployee sets the properties of the bean based on the input the 
user has made in the HTM L form (Figure 165). 


public void updateEmployee(HttpServletRequest request, HttpServl etResponse response) 
throws Servl etExcepti on, java. i o. IOExcepti on { 
response. setContentType("text/html ") ; 
response. setHeader("Pragma" , "no-cache") ; 
response. setHeader("Cache-Control ", "no-cache") ; 
response. setDateHeader(" Exp i res" , 0) ; 

// Get the output writer 

java.io.PrintWriter out = response. getWri ter() ; 

out .printl n("<HTML><HEAD><TITLE>Resul t</TITLE></HEAD><BODY>") ; 

HttpSession session = request. getSession(fal se) ; 

Employee emp = (Employee) 

session.getVal ue("i tso.wasdb.ejb. servl et. Employ eeEJBServl et.empl oyee") ; 
emp ,setLastName(getParameter(request, "1 astName") ) ; 
emp .set Fi rst Name (get Parameter (request, "firstName") ) ; 
emp. setPhoneNo (get Parameter (request, "phoneNo") ) ; 
emp. setMidl nit (get Parameter (request, "midini t")) ; 

emp .setSal ary(Doubl e. val ueOf (get Parameter (request , "sal ary") ) .doubl eVal ue() ) ; 
out.println("<Hl>Update ok</Hl>") ; 
out.println("</BODY></HTML>") ; 

} 


Figure 165. Set the Properties of the Employee Bean 

Testing the Servlet 

Start the WebSphere Test Environment and make sure that the EJ B Server 
is running. Open a browser and enter the URL: 

http :// 127. 0.0. 1:8080/ servlet /i tso.wasdb.ejb. servl et. Empl oyeeEJBServl et? 
empNo=000010 

The result of the empl oyee servlet looks similar to the department servlet 
(Figure 166). 



Figure 166. E mployeeEJ BServlet Output 
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Deployment of the Employee Bean to WebSphere 

The employee enterprise bean is deployed in the same way as the department 

bean, but there are a few differences: 

□ Export thej AR file (select Export ->EJ S J ar ). I n the export dialog, click 
on th eDetails button and add the EmployeeStorageclass. It is required at 
runtime to access the database. NamethefileEmp/oyeaEy S.jar. 

□ I n the WebSphere administration dialog for EnterpriseJ ava Services, the 
global settings are fine (Figure 140 on page 150), and we can usethesame 
ITSOContainer (Figure 141 on page 151). 

□ Select the £ mpl oyeeEJ S.jar file on the EJ B J ar Files page (Figure 142 on 
page 151) and click on Deploy. Select the ITSOContainer, and click on 
Redeploy Existing in the warning dialog (Figure 143 on page 152). 

□ Start the test client in VisualAgefor J ava and connect tothe deployed 
employee enterprise bean. 
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11 WebSphere Studio 

I n this chapter we briefly introduce the WebSphere Studio tools. 

We then describe in more detail the servlet generation wizards that allow 
easy creation of servlets with relational database access. 


©Copyright IBM Corp. 1999 
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WebSphere Studio Tools 

WebSphere Studio can help a Web team build powerful, e-business Web sites 
packed with features and interaction, without relying on the Common 
Gateway I nterface (CGI ) and Active Server Pages (ASP). 

WebSphere Studio combines easy-to-use wizards with site design andj ava 
development tools, simplifying and speeding the application development 
process. It combines graphical development wizards with tools for Website 
design andj ava development. 

These wizards and tools simplify and speed the application development 
process, and include: 

□ Web Development Workbench— A Web site project organizer and 
launch platform. 

□ Servlet generation wizards— For building J ava servlets to access 
J DBC databases andj avaBean components. 

□ Visual Age for J ava, Professional Edition V2.0— IBM's J ava 
application development environment for buildingj ava applications, 
applets, servlets andj avaBean components. 

□ NetObjects Fusion V3.0— Allows Web site developers to design and 
produce an entire Web site, including individual pages and all links.lt 
features automated site building, automatic link management, remote 
database access, and design and publishing capabilities. 

□ NetObjects BeanBuilder V1.0— The visual authoring tool for 
combiningj avaBeans andj ava applets, BeanBuilder allows individuals 
overseei ng the content of onl i ne busi ness processes to create more 
compelling, highly interactive Websites. 

□ NetObjects ScriptBuilder V3.0— Combines a text-based script editor 
and development tools for creating and editing HTM L, script, and 

J avaServer Pages (J SP). 

I n this chapter we only cover the servlet wizards and show how to use them 
to create simple database access servlets, the corresponding J SPs, and 
J avaBeans. 
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Installation and Configuration 

During our work we used WebSphere Studio 3.0 Beta 2 which was 
downloadable from http://www.so/tware. ibm.com/webservers/ . 

Although WebSphere Studio allow the specification of a class path, it seems 
to be important to put any class files, for example, db2java.zip for DB2 or 
dasseslll.zip for Oracle, in the system class path. Before you start 
WebSphere Studio make sure the necessary zip/jar files are in the cl ass path 
(Control Panel ->System ->Environment ->CLASSPATH). 

The next important point isto specify where WebSphere Studio stores the 
published files. Usually this isthe place where the WebSphere Application 
Server resides. U nfortunately one cannot change the preferences without 
having a project open. That is the reason why we come back to this point in 
"Publish the Project” on page 194. 

The examples described here are provided as archive files. Toopen them, 
select Fi!e-> Open Archive from the menu and select the Itso. war file from 
the Studio directory. Replace the content of the ITSO project with the extract 
of the Itso.war file. 


Project Setup 

The development of Websites is organized in projects in WebSphere Studio. 
Naturally thefirst step istocreatea new project that will be our playground. 
When WebSphere Studio is started thefirst time, it asks whether it should 
create a new project, use an existing project or exit. 

□ We want to create a new project. So click Create new in thefirst dialog 
(Figure 167). 


IBM Websphere Studio 


Would you like to create a new project, open an existing project, or exit 
Studio ? 


SI 


[ Create New 


Open Existing 


Exit Studio 


Figure 167. Create New Project 

□ Now specify the name ITSO for the project (Figure 168). 
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Figure 168. Specify Project Parameters 
□ You should now have a project window (Figure 169). 



Figure 169. WebSphere Studio Project Window 
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Create an SQL Statement and Servlet 


To compose a database query and let WebSphere Studio create a servlet, we 
use the SQL Wizard: 

□ Select the project ITSO on the left side. 

□ Fromthetool bar select SQL Wizard (Figure 170). 



Figure 170. WebSphere Studio Tool Bar 

□ I n the SQL Wizard dialog you have to provide a name for the SQL 
statement. I n this example we want to select employees and some data 
from their department from the database. The records will be selected by 
partial employee last names. Therefore we name the new SQL statement 
E mpl DepByE mpl N ame (F igure 171). 



F i gure 1 71 . Sped fy a Name for the SQL S tatemen t 
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□ The next step is to provide the wizard with the necessary database 
connection information (Figure 172). As usual, we provide the foil owing 
for DB2: 

• Driver: IBM DB2 UDB local (COM .ibm.db2.jdbc.app.DB2Driver) 

• URL: jdbc:db2:itsowdb 

• User I D and password: ITSO and itso (as in all examples) 

To close the dialog, weclick on Connect. 



F i gure 1 72. Sped fy the C on need on Parameters 

Note: For Oracle you would specify j dbcorad e:thi n :(3I ocal host:1521:orcl 
for the database URL and Orac/efor the driver. For SQL Server you would 
specify jdbc:odbc:SQLServer for the database URL andy DBC-ODBC 
Bridge for the driver. 

□ On the Tables page select the two tables, department and employee, of the 
database (Figure 173) and click Next. 
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Figure 173. SelectT abl es from the Database 


□ On thej oin page, specify an inner join by selecting DEPNO in the 
department table and WORKDEPT in the employee table and click on 
J oin (Figure 174). 


Welcome 

Logon| Tables 

Join 

Columns 

Condition 1 1 Sort 

SQL 

Finish | 


Show how the tables are related by joining them. 



F i gure 1 74. Sped fythej oi n 
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□ On the Columns page we select the columns to display (Figure 175). 
During the time this book was written, the data access bean seemed to 
have problems with date fields (see "Data Access Beans" on page 266). To 
avoid troublefor the time being, it is better not to select a datefield. 



Figure 175. Specify theColumns to Display 

□ On the Condition 1 page we specify the condition for the select statement 
(Figure 176). 

Select the EMPLOYEE table, theLASTNAM E column and the contains 
thecharacter(s) operator. Now we have to enter a host variable for the 
value of the condition. We click on the first text field and then on the 
Parameter button. A dialog to name the parameter pops up and weenter 
lastName. Parameter values aredisplayed in bold face in the text field 
whereas fixed values aredisplated normal. 

This specification generates a WFIERE clause of the format: 

LASTNAME LIKE '%' | |?| | '%' 
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Figure 176. Specify theConditions 

□ Because we do not want to sort the output we can now view the complete 
SQL statement (Figure 177) and then generate the code by clicking on the 
Finish button. 


SELECT ITSO. EMPLOYEE. FIRSTNME, ITSO . EMPLOYEE . LASTNAME , ITSO . EMPLOYEE . PHONENO, 
ITSO . EMPLOYEE . JOB, ITSO. EMPLOYEE . SALARY , ITSO . DEPARTMENT. DEPTNAME 
FROM ITSO. DEPARTMENT, ITSO. EMPLOYEE 
WHERE ( (ITSO. EMPLOYEE. WORKDEPT = ITSO. DEPARTMENT. DEPTNO) AND 
(ITSO. EMPLOYEE. LASTNAME LIKE , %'||?|| , %') ) 


Figure 177. Completed SQL Statement 

The WebSphere project window now contains a new file named 
E mpl DepByE mpl N amesql . This file is the basis for the next step, that is, to 
create a servlet that accesses the database using this SQL statement and to 
create the corresponding] avaServer Pages that provide the input and output 
for the servlet. 
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Create the Servlet and JSPs 


The SQL query is ready and can be used in the Database Wizard to create a 
servlet andaj SPO. Select the Database Wizard from the tool bar (Figure 170 
on page 183) or from the menu. 

□ We only have one query so far, E mpl DepByE mpl N amesql . It should be 
selected by default, if not select it from thecombobox (Figure 178). Click 
Next. 



Figure 178. Select theSQL Statement 

□ The next step is to select what Web pages should be created (Figure 179). 
Because WebSphere Studio3 beta 2 and WebSphere Application server 
2.0.2 are a little inconsistent at the moment, you should not use the last 
option. For an explanation see "WebSphere Studio" on page 267. Click 
Next. 
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Web Pages 



The wizard can create web pages for you automatically. 

If you decide not to create these pages now, you can 
always create them later. 

|7 Create an input page. 

17 Create a results page. 

17 [Create a page for when an error occurs : 
r Create a page for when no data is returned. 

When using database access, you can choose the 
following options: 

Allow Update 

f~ Run as transaction 


< Back 


Next > I Cancel 


Help 


Figure 179. Select the Generated Pages 

□ Now we specify the parameters that will appear on the input page. We 
need at least the lastName parameter (Figure 180). Click Next. 


Input Page 


Check the fields you want to display on your input page. You can also change the settings for 
each field and reorder the fields. 


Name 

Type 

1 Caption 

1 Size 

1 Maximum Length I Initial Value I .*. 

PI driver 

java. lang. String 

driver 

20 

20 

0 lastName 

java. lang. String 

lastName 

20 

20 ▼ 

0 password 

java. lang. String 

password 

20 

20 

□ URL 

java. lang. String 

URL 

20 

20 

□ userlD 

java.Iang.String 

userlD 

20 

20 


Change... | Check All | Uncheck All | 


< Back 


Next > 


Cancel 


Help 


Figure 180. Specify input Parameters 
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□ This next step is similar, but specifies the parameters for the resulting 
output page (Figure 181). We select all the table columns, but are not 
interested in the database driver, URL, SQL statement, and user ID, 
although this might be useful for testing purposes. Click on Next 



Figure 181. Specify the Fields for the Result Page 

□ I n the next step you may add your own error message or you might even 
specify your own error page. We do not have our own error handling for 
now, and therefore we use the default. 

□ The next step is to select which methods of the generated J avaBean have 
to invoked and in what order. Because we only have one method, the 
execute method, we do not change anything. The execute method does the 
actual query. 

□ Now we may specify whether the query is used in more than one output 
page. If so, this step enables us to attach the bean to an HttpSession 
object, which is then accessible by more than just thedirect J SP output 
page. 

If multi pie output pages are not selected, the resulting bean is just part of 
the request object and is only accessible from thej SP result page of the 
generated servlet. 

For this simple example we do not select multiple output pages (Figure 
182). 
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Session 



Will you use this bean or query on more than one page? 
C~ Yes, store it in the user's session 
(• INd 


When using the same bean or query on more than one 
page, you should use the same name for it on every 
page. What name would you like to use? 


iBearAlias 


< Back | Next > | Cancel | Help 


Figure 182. Specify to Use the Bean in a Session 

□ The last step is to give more detailed information to the servlet generator 
regarding thej ava package ( itso.wasdb.studio ) and the name of the file. 
To provide that information, click the Advanced button in the Finish 
dialog and provide the package name and the prefix (Figure 183). 



Figure 183. Provide Package Name and Class Name Prefix 
□ The Finish dialog is shown in Figure 184. Click the Finish button. 
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Finish 



That's it. When you dick finish, the following files will be 
created for you. 


Description 

File Names 

Input Page 

Results Page 

Standard Error Page 

No Data Exception Error Page 
Database Bean 

Database Java Servlet program 
Servlet Configuration File 

EmpIDeptlnputPageT 

EmpIDeptResultPage 

EmpIDeptErrorPage.js 

EmpIDeptNoDataErro 

EmpIDepByEmpINami 

EmpIDept.java 

EmpIDeptServlet.serv 

±1 

1 Jj 


Advanced.... 



Figure 184. F inish the Wizard 


Project View after the Database Wizard 

The project view should now show a few more files (Figure 185). 



Figure 185. Project after Servlet Generation 
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Here is a description of the newly generated files: 

□ EmpIDepByEmpINameJava and EmpIDepByEmpINam&class are 

thej ava source and class files for the bean that represents the actual 
database query. The bean uses the IBM data access bean and the IBM 
connection manager to access the database. It offers several methods; the 
most important one is the execute method, which performs the query. 
Moreover, for each output column selected in Figure 181 on page 190, it 
offers a getCOLU M N _NAM E method, which returns the particular value 
for that col umn of the query. 

□ EmpIDep.java and EmpIDep.class are the J ava source and class files 
for the generated servlet. The servlet is derived from the PageListServlet 
class. That means the pages that are cal led from this servlet are not 
hard-coded, but specified in the servlet configuration file 

E mpl DepServI et.servl et. The most important method is the performTask 
method. It reads parameters from the servlet configuration file (user I D, 
password, database driver, URL). It also reads the input parameters 
specified in Figure 180 on page 189 from the request, initializes the 
database bean E mpl DepByE mpl N a me with the necessary parameters, 
and invokes its execute method. Additionally, it adds the instance of the 
£ mpl DepByE mpl N a me bean to the request, then cal Is the output 
J avaServer Page. 

□ E mpl DepServI et.servl et\s an XM L-based configuration filethat sets the 
rules for the servlet. It regulates which page is to call when the servlet 
has successfully accessed the database, and also which page is to invoke 
in case of an error or in case no data was found. Furthermore, it contains 
key/value pairs for the user I D, the password, the database driver, and the 
URL. 

□ EmpIDepI nputPage.html is an HTML simple input page that enables 
the user to enter a val ue for the lastName parameter and then invokes the 
EmpIDep servlet. 

□ EmpIDepResultPageJsp is thej avaServer Page that is called from the 
servlet after successfully accessing the database. To display the results it 
uses the £ mpl DepByE mpl N a me bean that was instantiated by the servlet 
and given to this page through the request block. 

□ EmpIDepErrorPageJsp is thej avaServer Pagethat is called in case of 
an error. 
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Publish the Project 

The final step for this sample servlet is to deploy all the generated files to the 
WebSphere application server, that is, to publish the files to the server. 

We have to make sure that WebSphere Studio publishes the files to the 
proper directories for the HTTP Server and WebSphere. If you have used a 
default installation, WebSphere searches for servlets under: 

c:\WebSphere\AppServer\servl ets 

and the IBM HTTP Server is looking for HTM L files in: 

c:\Program Files\IBM HTTP Server\htdocs 


Publishing Configurations 

There are three possible configurations between WebSphere Studio and 

WebSphere Application Server: 

□ In case WebSphere Studio and the WebSphere Application Server are on 
the same machine, we check that the publishing properties of the server 
are correct. We switch tothe publishing view in the project window by 
selecting V7ew ->Publishing, or alternatively by clicking the appropriate 
icon from the tool bar. Open the properties from the context menu of the 
server (Figure 186). 



Figure 186. Specify Publishing Options 

In the properties dialog, click on the Default Publishing Target button 
(Figure 187). M ake sure the sure the targets match your configuration. 
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Figure 187. Publishing Server Properties 

□ In case WebSphere Studio and the WebSphere Application Server are on 
different Windows machines but the machine with the Application Server 
is accessible as a shared drive, the publishing is almost the same, except 
for the fact that the server nameis not / oca I host. You may specify this also 
in the server properties dialog (Figure 187). 

□ In case the WebSphere Application Server ison a machine that is not 
accessible as a shared drive, usean FTP upload mechanism to publish the 
files to the application server. Again the server properties dialog (Figure 
187) is the place to detail the FTP parameters. 

Once the publishing configuration is specified, we can publish the files to the 
Application Server and the HTTP Server. From the context menu of the 
server http: //myserver select Publish thisServer. In the first dialog that is 
displayed you may specify additional options. For our example, no changes 
are required. I n the next dialog we can select the files to be published; the 
default selection is correct for this step as well. 
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Assembly Stages 

WebSphere Studio has two predefined assembly stages, test and production. 
Select VieN -> Assembly Stage to switch between thetwo stages. 

You can definethetest assembly stage for local publishing (localhost) and the 
production assembly stage for publishing to another Webserver. Set up the 
properties and publishing targets for both assembly stages. 


Publishing Targets 

The publishing target dialog defines the two directories for publishing 
HTM L/J SP files and servlet classes (Figure 188). 


Publishing Targets 


3 


Publishing T argets: 


_NameJ Path 

Add 

ihtmi S:\ProgramFiies\iBMHTtPServer\htdocs 

Remove 

Browse... 

servlet T:\WebSphereV\ppServer\servlets 


OK 


Cancel Help 


Figure 188. PublishingTargets 
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Testing the Generated Servlet 

Testing is easy and straightforward once the project has been published to 
WebSphere. F rom the context menu ofth e E mpl Depl nputPagehtml file 
select Preview ->netscape or iexpl ore depending on the favorite browser 
(Figure 189). 


B http://sonoma 


B C| servlet 
B "d theme 

* £ j Master.css 
V til EmpIDepErrorPage.jsp 


EmpIDepIn 


t Tj| EmpIDepRe: 


Edit with 


Preview File with 


Auto Preview Files 


Cut 

Copy as URL Text 
Copy as HTML Tag 


Delete... 

Check In 
Undo Check Out 
Publish this File 


► \ 

iexplore 

netscape 


Figure 189. Select Preview from the Context Menu 


The FITM L input page is plain but functional (Figure 190). 



Figurel90. Generated HTM L Input Page 
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The HTM L output page that is generated by thej SP displays the result of 
the simple servlet (Figure 191). 



Figurel91. Generated HTM L Output Page 


Enhanced Insert Example 

In the second examplewe will develop a simpleservlet that inserts a new 
employee in the database. With the help of the Studio Wizards this is also a 
very simple process. I n the second step we will enrich the input page of the 
insert servlet sothat it already shows all available department numbers in a 
combobox. Because the department number is a foreign key in the employee 
table, this assures that only existing values will be inserted. 


Create an SQL Statement 

The first step is to create an SQL statement with the SQL Wizard: 

□ N ame the SQL statement / nsertE mployee 

□ Provide the connection parameters. 

□ Select the employee table and make sure you select Insert for the SQL 
type (Figure 192). 
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Figure 192. Creating an I nsert Statement 

□ Select the columns that are inserted. The columns with the blue 
background are not null columns in the table, thereforethey are 
mandatory (Figure 193). I n addition to the mandatory fields we select the 
PHONE NO and the WORKDEPT field. 


Entervalue(s)forthe new row to insert. 

Available columns with value(s) to insert (+ designates a required column): 


Column / 

Type 

3 

Value 

+ EMPNO 

CHAR (Type 1)(6) 

= 

erfrilo 

— 

+ FIRSTNME 

VARCHAR (Type 1 2)(1 

= 

firstHame 


♦ MIDINIT 

CHAR (Type 1)(1) 

= 

mi (Unit 


+ LASTNAME 

VARCHAR (Type 1 2)(1 

= 

lastHame 


WORKDEPT 

CHAR (Type 1)(3) 

= 

workDept A 


PHONENO 

CHAR (Type 1)(4) 

= 

phoneHo y 


HIREDATE 

DATE (Type 91) 

= 


▼ 

U 



1 jU 


Figure 193. Select the Input Fields 
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□ The resulting SQL statement is shown in Figure 194. 


INSERT INTO ITSO. EMPLOYEE 

( EMPNO, FIRSTNME, MIDINIT, LASTNAME, WORKDEPT, PHONENO, EDLEVEL ) 
VALUES 

( ?, ?, ?, ?, ?,?,?) 


Figure 194. Generated SQL I nsert Statement 


Create a Servlet 

With the SQL statement specified, the next step is to create a servlet based 
on that statement. We use the Database Wizard: 

□ Select the I nsertE mplyee.sql statement that was just created. 

□ Create an input and result page. 

□ Select the input fields empNo, firstName, midi nit, lastNamp edLesel, 
phoneNo, and workDept. You might also want to sort them usi ng the up 
and down arrows on the right side. 

□ Select columns for the results page, for example firstNameand lastNama 

□ Select the execute Method in the next step. 

□ We do not use the bean in more than one page, so no change is necessary 
in the next dialog. 

□ Finally specify the advanced parameters, that is, the package name 
itso.wasdb.studio and a meaningful prefix, for example InsertEmpl. 

□ Click Finish to generate the code. 

□ Publish the project. 

Viewing the Result 

The input page is shown in Figure 195. Notice that the user is allowed to 
specify any working department number regardless of whether the 
department exists or not. 

It would be nice to enhance this process to allow the user to select only 
existing department numbers. This is what we will do next. 
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ah«p://sonoma/lnsertEmpllnputPage.html - Microsoft Internet Expl... BED 



_J Local intranet zone 

Figure 195. Insert a New Employee 

Determine all Available Department Numbers 

To enhance the input form with a combobox that displays all the available 
department numbers, we create an SQL statement to retrieve them. 

This step is quite easy with the SQL Wizard: 

□ Create a new SQL statement named Al I DepN umbers. 

□ Provide the connection parameters. 

□ Select the department table. 

□ Select theDEPTNO column to include (Figure 196). 

□ That is all. Click Finish. 
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Select the columns you wish to include. 


Selected table(s): 


ITS 0. DEPARTMENT 


E 


Columns: 

DEPTNAME 

MGRNO 

ADMRDEPT 

LOCATION 


Select all | 
Deselect all | 


Columns to include: 
ITSO.DEPARTMENT.DEPTNO 


Move up | Move down 


Figure 196. Select the DEPNO Column 

Based on this statement, we create a servlet using the Database Wizard. 

□ Although we actually do not need input and output pages, we will create 
an output page because the PageListServlet class apparently requires it. 
Later, when the servlet is created, we will modify the source slightly, so 
that no output page is called and we can also delete the output page. 

□ Continue to the session step. Give the bean a meaningful name, for 
example, change it from BeanAlias to depN umbers. 

□ Continue to the end; no changes should be necessary. Specify as usual the 
package itso.wasdb.studio and the prefix All DepN umbers, and finish the 
wizard. 


Invoke the Servlet from a JSP 

We want to use the servlet we just created as an input for the page where we 
specify the new employee, that is in the I nsertE mpl I nputPagehtml . We use 
the HTM L page as a base and modify it and create a J SP file. 

Open the page by doubleclicking on it. The WebSphere Studio Page Designer 
is started (Figure 197). This is the HTM L/J SP editor of WebSphere Studio. 
We will not provide an introduction in the usage of this editor, but you can 
use it to enhance the generated i nput and output pages. 

We will use the editor to add the invocation of a servlet, theAllDepNumbers 
servlet, and at the same time add the bean that is created by the 
Al I DepN umbers servlet. This process makes it possible to use the bean to 
createa comboboxthat holds all the possible department numbers retrieved 
by the database query. 
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Figure 197. WebSphere Page Designer 

□ Start by adding a servlet invocation to the top of the page. Use the menu 
I nsert -> Servlet. I n the dialog specify the name of the servlet to be 
invoked, in our case the Al I DepNumbersServlet (Figure 198). Enter 
itso.wasdb.studio.AIIDepN umbersServlet as the code attri bute. 

lag: | SERVLET ^ 

SERVLET | Initial Parameters | Parameters | 

Name: 

Code: | itso.wasdb.studio.AIIDepN umbers) 

Code Base: 


Author Time Visual 

Setting... | ^^elete^J 

Figure 198. Specify the Servlet to be! nvoked 
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This specification generates the code 

<SERVLET code="i t so. wasdb. studio. A1 1 DepNumbersServl et"> 

</SERVLET> 

□ The next step is to insert the bean, also at the top. Select Insert ->) SP 
Tags ->Bean Tag from the menu. The name of the bean is depN umbers 
(the name we gave a few steps earlier) and the type of the bean is 
itso.wasdb.studio.AIIDepN umbersBean (Figure 199). 


|bean 

z\ 

J | Parameters | 

i 


lag: 


Name: 

Varname: 

lype: 

Introspection: 

Beanname: 

Create: 

Scope: 


I depN umbers 


| itso. wasdb. studio. AIID epN umbersB ean 
C Yes C No 


C" Yes 


C No 




OK 


Cancel 


Help 


F i gure 1 99. Sped fy Bean Parameters 

This specification generates the code 

<BEAN rame=“depNumbers'' type="i tso. wasdb. studi o.Al 1 DepN umbers Bean “> 
</BEAN> 

□ Delete the last text field (the working department) and substitute it with 
a combobox. The result page should now contain one servlet tag, one bean 
tag, and a combobox instead of a text field (Figure 200). 
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Servlet and Bean 


{JX4> 



Figure200. Resulting Page 

□ Next, you have to provide the possi ble val ues for the combobox that are 
dynamically retrieved by the All DepN umbers servlet. 

Double-click on the combobox and specify the name workDept in the 
dialog. This is the name the text field had when we specified it with the 
database wizard (Figure 193 on page 199). 

□ I n the same dialog switch to the Dynamic pane. This is the pi ace to 
provide the combobox with possible values. 

To retrieve the values dynamically, we select the Loop Property and click 
on Browse. Another dialog is displayed wherewecan browse the available 
properties of all the beans accessible from this page (Figure 201). Browse 
the depN umbers bean and select the ITSO_DEPARTMENT_DEPTNO 
property. 

□ On the same page specify the/ tern Property that is displayed in the 
combobox. I n this case it is the same as the loop property (Figure 201). 

Select Specify as Property and browse once more to the 
ITSO_DEPARTMENT_DEPTNO property. If we had specified morethan 
one output field in the Database Wizard (for example, the department 
name), such fields could also be used here. 
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Figure 201. Selecting theLoop Property 


□ Switch to the Html SourceView and look at the generated code for this 
table cel I (Figure 202). 

The first cel I of the table row contains the word workDept. The next cell 
contains the dynamic content that is evaluated and replaced by the 
WebSphere Application Server at runtime. Basically, we specified which 
property is iterated and which property is displayed as a value. I n our 
case, both are the same property. 
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<TR><TD>workDept</TD><TD> 

<!--METADATA type="Dynami cData" startspan 

<S ELECT dynami cel ement loopproperty="depNumbers. ITSO_DEPARTMENT_DEPTNO() " 
i temproperty="depNumbers. ITSO_DEPARTMENT_DEPTNO() " name="workDept" </SELECT> 
--><% 
try { 

java.l ang. String _pO = depNumbers.getITS0_DEPARTMENT_DEPTN0(0) ; 

%><SELECT name="workDept"><% 
for (int _i0 = 0; ; ) { %> 

<0PTI0N><%= _p0 %></0PTI0N><% 

_i0++; 
try { 

_p0 = depNumbers .getITSO_DEPARTMENT_DEPTNO(_iO) ; 

} 

catch (java.lang.ArraylndexOutOfBoundsException _e0) { 
break; 

} 

} %> 

</SELECT><% 

} catch (java.lang.ArraylndexOutOfBoundsException _e0) { 

} %><!--METADATA type=" Dynami cData" endspan--> 

</TD></TR> 


Figure 202. Generated Codefor Dynamic Item Values 

Everything is ready. You might want to enhance the look of the page. Also, 
you might want to inspect the generated J SP and HTML code. 


Save the Modified HTML Page as a JSP 

Because we imbedded J ava logic into the HTM L page, we have to execute the 
page as a J SP. 

Save the page ( File->SaveAs ) as / nsertEmpI I nputPagejsp and select Add to 
WebSphere Studio in the save dialog. The Beta 2 product complains with an 
error message that this is not possible and then asks you to save again. J ust 
save again, and although WebSphere Studio complained, everything works 
fine. 


Modify the Generated Servlet 

The final step is to modify the generated source of the AIIDepN umbers 
servlet. The servlet is generated by WebSphere Studio and by default it is 
derived from the PageListServlet. 

A PageListServlet is configurable by the matching servlet XML configuration 
file (AIIDepN umbersServlet. servlet). This configuration file contains some 
parameters for the servlet, such as the database user I D, password, the 
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driver, and the URL. It also specifies which output page is the default result 
page for the servlet, which page is the error page, and all theother possible 
output pages. 

I n our case, we do not want an output page cal led by the servlet. For this 
reason, we change the source code of the servlet: 

□ Open thej ava source file of the servlet, that is, Al I DepN umbersjava. It 
has several methods; the most important one is the per for mTask method. 
At the very end of this method, you will find the foil owing line: 

cal 1 Page(getPageNameFromRequest(request) , request, response); 

Comment it out. Theeffect is simple. TheoutputJ SP page we had 
configured is not called anymore. 

This is exactly what we would I ike to achieve, because the servlet is 
already called from a J SP and the output of the servlet is the depN umbers 
bean, which is included in the output J SP. 

□ Save the file and select Compile from thecontext menu in WebSphere 
Studio. 

□ Finally select the server and publish the project to the server. 

Test the JSP and the Servlet in WebSphere 

After publishing thecodetothe WebSpere Application Server we can test the 
J SP and the servlet. 

Select Preview ->iexplore or navigator from the context menu of the 
I nsertEmpll nputPagejsp from the Publish view. As you can see in the 
browser, the working department now contains a combobox with all available 
department numbers (Figure 203). 

Problem with Servlet Configuration 

Thej SP calls theAUDepN umbers servlet. When loaded, the code looks for 
the servlet configuration file, All DepN umbers, servlet, but the generated file 
is named Al I DepN umbersServlet.servlet. 

We copied the Al I DepN umbersServI et.servl et file as All DepN umbersservlet 
and depl oyed that copy i nto the same directory. 

Note: Wealsotried to call the servlet by the name All DepN umbersServI et 
(Figure 198 on page 203), but then the load of the servlet from thej SP 
servl et fai I ed compl etel y. 
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F i gure 203. E nhanced I nsert S ervl et I nput Page wi th C ombobox 
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Debugging the Servlets in VisualAge for Java 

Here are the steps required to debug the generated servlets in VisualAge for 
J ava. 

□ As a prerequisite, the ITSOWDB database must be available and 
accessible through the same J DBC drivers, URL, user ID, and password 
as specifed for WebSphere. 

□ I mport the six servlet source and bean files (.java) intoth elTSO SG24 
5471 project in VisualAge for J ava. The itso.wasdb.studio package is 
created. 

□ Error messages are reported for each servlet. 

import comm. i bm.webtool s . runtime.*; <=== missing package 

This package is not required, therefore you can delete the linefrom each 
servlet. 

□ Copy the HTM L and J SP files to the proper HTM L directory. If you 
performed a local publishing, the files should be there already. 

□ Copy the servlet configuration files (.servlet) into the resources directory: 

c:\IBMVjava\ide\project_resources\ITSO SG24 547 1 \ i tso\wasdb\studi o 

Make sure that you have the Al I DepN umbers.servl et file (copy of 
At ID epN umber sS ervl et. servl et) . 

□ Start the WebSphere Test Environment and open a browser with the 
URL: 

http:// 127. 0.0. 1:8080/Empl DeptInputPage.html 
http://127.0-0. 1:8080/ Insert Empl nputPage. jsp 

□ You can set breakpoints in theservlet code to activate the debugger. 
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Hints and Tips for WebSphere Studio 

The beta code of WebSphere Studio has some problems that may disturb 
smooth operation. Here are a few pointers on how to deal with problems. 


Synchronization between Development and Publishing View 

It seems that sometimes files of the development view (left side of the project 
view) do not show up in the publishing view (right side). Th eSync left view 
and right view push button in the tool bar does not work (Figure 204). 

You can force a filetothe publishing view by selecting it, open its properties, 
and on the Publishing page deselect the Set pub! i shabl e checkbox. Click OK. 
Then open the properties again, select the checkbox, and click OK. This 
copies the filetothe publishing view. 


Checkout 

Files that have been edited have the checkout flag (a red check mark). You 
can select thefileand select Check In from thecontext menu. 

I n the directory structure, checked out files are in the directory: 
c:\WebSphere\StudioBeta\check_out\. .projectrame. . . 

Files that are checked in are marked read-only in the directory: 

c:\WebSphere\StudioBeta\projects\. .projectrame. . . 


Publishing Warnings About Old Class Files 

When publishing, wegot a warning message that theclass file (.class) was 
older than the source file (.java). I n such situations you can check out the 
source and class files and compile the source file (select Compile from the 
context menu). After that check both files in. 


Mismatch between Servlet and Servlet Configuration 

For a servlet called from a J SP, the naming of the servlet (.java) and servlet 
configuration file (.servlet) does not work. See "Problem with Servlet 
Configuration" on page 208 for a circumvention. 
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Project View 

Figure 204 shows our project view after completing all the samples. 
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Figure 204. Complete Project Vi aw 
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12 WebSphere User 
Profile 


I n this chapter we describe the user profile function of WebSphere. We also 
develop a sample servlet utilizing the user profile function. 


©Copyright IBM Corp. 1999 
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Description 

The WebSphere Application Server includes classes in the 
com. i bm.servl et.personal i zati on. userprofi I e package that make it easier to 
maintain persistent information about your Web site visitors and use that 
information to customize your Web pages. 

At the time of the release of the WebSphere, the classes of the package 
com. i bm.servl et.personal i zati on .userprofi I e are considered a reference 
implementation, because issues, such as database schema and runtime 
environments, can vary greatly from application to application. Given these 
considerations, WebSphere includes the source of the UserProfi led ass and 
an example of how to extend the class. Both source files are in the 
h iebSphere\AppServer\samples\userprofile directory. The only coupling between 
the UserProfi I edass and the rest of WebSphere is that the UserProfi led ass 
and IBM's session implementation (/ BM Session Data) have a user name field 
that can be used to create some synergy between the two cl asses. 

The UserProfile class includes data members for a visitor's complete name, 
postal and e-mail addresses, and telephone numbers, and has fields to store 
language of choice, employment, and user-defined group information. In 
addition, it has a generic message, a shopping cart, and a clipboard that is a 
J ava hash table. This allows you toeasily incorporate other objects of your 
choice into these data members and handlethem as part of the UserProfile 
class. Because these objects are persistent across successive instantiations of 
the UserProfile, they must be serializable. If you use a J DBC database, the 
objects will be stored in the database. Otherwise, they will be stored as files. 

I n the WebSphere Application Server Version 2.0, the U serP rofi I e cl ass uses 
the database connection manager to maintain J DBC connections. 


Configuration 

To set up the user profile function, you should use WebSphere’s 
administration dialogs. Once you have started the administration program 
(see "WebSphere Configuration" on page 6), select Setup -> User Profile. 


Enable Page 

On the Enable page select yes for Using UserProfile? (Figure 205). As you can 
seethe UserProfi I eel ass itself can be modified. So if your application has 
some specific needs where it requires modifying the code, you can do so and 
can place the modified class name in here. 
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<3 Ready 

people who visit the Web site. 


WebSphere Application Server ] f |J<j 0 p Pfofjl© 


D Introduction 

▼O Setup 

0 Administration 
0 Connection Management 
0 Directory Management 
O Java Engine 
0 Session Tracking 
0 User Profile 
0 Virtual Hosts 

► □ Servlets 

► O Enterprise Java Services 

► O Security 

► O Server Execution Analysis 
0 Log Off 




Save | 

Revert | 

Defaults | 


Enable | Database ~|" 


ConnMgr 


Using User Profiles? ^ |Yes| C No 

Class Name: | com. ibm. servlet. personalization, userprof ile. U serProf ile 


A±C 


Figure 205. E nabling User Profile 


Database Page 

The database information required here is based on the URL used for the 
J DBC connection. Every database server has its own URL and each differs 
from the other. The way in which the UserProfile uses the information is as 
follows: 

URL: jdbc:" +Config.DBUSED +Config.DB_NAM E; 

Table Name: Config.DB_OWNER +Config.USER_TABLE 

Figure 206 shows the specification for DB2, Figure 207 for Oracle, and Figure 
208 for SQL Server. 
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DB2 


Save 

Enable | Database | ConnMgr 


Revert | 


Database Used:| db2 

I 


Defaults | 

JDBC Driver used: 1 COM ibm db2.)dbc app.DB2Driver 




Database Name:| itsowdb 




Database Owner: itso 




Table Name:| UserProfile 




User ID: | itso 




Password: 



Figure 206. UserProfileDatabaseSetup for DB2 


Oracle 


Save 

Enable | Database | ConnMgr 

Revert | 



Database Used:! oracle:thin:@localhost:1521 

Defaults | 



JDBC Driver used:! oracle.jdbc.driver.OracleDriver 



Database Name: orcl 




Database Owner: itso 




Table Name:| UserProfile| 




User ID: | itso 




Password: ”” 




Figure 207. UserProfileDatabaseSetup for Oracle 
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SQL Server 


Save 
Revert | 
Defaults | 


Enable | Database | ConnMgr 

Database Used: 

JDBC Driver used: 

Database Name: 

Database Owner: 

Table Name: 

User ID: 

Password: 


odbc| 


sun.jdbc.odbc.JdbcOdbcDriver 


SqIServer 


itso 


UserProfile 


itso 


Figure 208. UserProfile Database Setup for SQL Server 

Connection Manager Page 

On the ConnMgr (connection manager) page you select the pool with respect 
to the database you have selected on the Database page (Figure 209). 

Enable | Database | ConnMgr 

Connection Pool Name:|Jd bcDb2| ~^1 
Wait if Connection Manager is not available? Yes <• No 


Figure 209. U serP rofi I e's Connection Pool Selection 


Save 
Revert | 
Defaults | 
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Click on Save and log off. The changes for the user profile only take effect 
when you stop the Web server and WebSphere. Then restart the Web server. 

The User Profile table is created the first time an attempt is made to access 
the user profile function. 


User Profile Create, Update and Retrieve 

In this section we briefly describe how to create, update, and retrieve the user 
profile from thedatabaseto provide you with some understanding on how the 
user profile works. 


Create 


Creating the user profile using new UserProfilef) does not result in writing 
the user profile into the database. To create an entry in the database table 
use insertToDatabasefU serP rofi I euserProf). When using the 
insertToDatabase method, the U serProfile passed to it must already have the 
U serName property set up, because there is no method for setting the 
UserName. Therefore you cannot call new UserProfile() and then pass the 
newly created class to the insertToDatabase method. 

The way to create a U serProfile would be using the static method 
addU serProfile. This method has three variations, which are: 

□ U serP rofi I e addU serP rofi I e(Stri ng userName) 

I n this method the userName is directly passed, and the returned 
U serProfile does contai n the userName. You can set the rest of the 
parameters using the setter methods available in the U serP rofi I eel ass. 

□ U serP rofi I e addU serP rofi I e(H ttpSessi on httpSession) 

I n this method the session object is expected to have a parameter called 
userN ame of type String. This can be done with a method call such as 
httpSessi on. putValue("userNamd‘, userName). Once the userN ame is 
extracted from the session, addU serP rofi I efuserN am^ is called to create a 
U serProfile. From this point on, other parameters are extracted from the 
session, if any of them is set, and the appropriate setter method is called. 

Note:Theextraction of parameters from the session and cal ling the setter 
methods is done behind the scene. 

□ U serP rofi I e addU serP rofi I efH ashTabl e cl i pboard) 

I n this method the hash table object is expected to have a parameter 
called userN ame of type Stri ng. This can be done with a method call such 
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as clipboard. put("userNamd',userName). Once the userN ame\s extracted, 
the addUserProfi I efuserN ame) is called. After that point, other 
parameters are extracted and the appropriate setter method is called. 

Note: The extraction of parameters from the hash table and calling the 
setter methods is done behind the scene. 

The second and third methods are merely wrappers functions that call the 
first method. 


Update 

You can update all of the fields except the userN ame \n a UserProfile object: 

□ void updateUserProfile(HttpSession sess) 

I n this method the session object is expected to have a parameter called 
userN ame of type S tri ng. 

□ void updatdU serP rofi I efHashtable clipboard) 

I n this method the hash table object is expected to have a parameter 
ca 1 1 ed userN ame of type S tri ng. 


Retrieve 


There are several ways to retrievea UserProfile object: 

□ U serP rofi I e retri evei) serP rofi I eByU serN ame(Stri ng userN ame) 

Based on the userName the UserProfile is returned. 

□ U serP rofi I e retri eveLI serP rofi I e(String type String key) 

type is the column namein the UserProfiletable and key is the value of 
the column. 

□ E numeration retri eveU serP rofi I es(Stri ng type, String key, Statement s) 

I n this method a statement is assembled based on the type and method 
returned. The results are 0 or multiple user profiles returned through an 
Enumeration object. 

There are several other methods in the U serP rofi led ass that can be used to 
retrieve the UserProfile based on different properties, for example, 
retri eveU serP rofi I esB yL anguage 
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UserProfile Example 

I n this example we want to demonstrate how the UserProfile is created and 
accessed. Also the usage of a shopping cart in the UserProfile context is 
discussed. 


Classes and Methods 

In this example we have employed J avaBean, J SP, and Servlet 
methodologies. The package i tso.wasdb.userprofi I e contains the classes used 
in this example. The following is the list of classes (Figure 210). 


a S3 itso.wasdb. userprofile 
— a © Item 
— ffi © ItemBeanlnfo 
— ffl © UserCart 
— IB © UserCartBeanlnfo 
— B © UserProfileCartServlet 

F i gure 21 0. i tsowasdb.userprofile Class L i sti ng 

Item 

Item is a J avaBean class that is passed as a shoppingCart object to a 
UserProfile. The properties are: 

String item; /* name of the item */ 

String price; /* price of the item */ 

An ItemBeanl nfo class is generated by Visual Age for J ava when th eltem 
class is created. 

UserCart 

UserCart is a J avaBean class that contains the basic information used to 
create a UserProfile. The properties are: 

String language; 

String firstName; 

String midName; 

String lastName; 

String userName; 

A U serCartBeanl nfo class is generated by VisualAgefor J ava when the 
UserCart class is created. 
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Note: The two cl asses Item and UserCart are simple J ava Bean classes with 
getter and setter methods. We will not describe these cl asses in detail 
because they do not need further explanation. 

UserProfileCartServlet 

The UserProfileCartServlet cl ass handles all of the incoming requests and 
outgoing responses. It is within this class where all of the transactions take 
place. Figure 211 shows the methods of the UserProfileCartServlet class. 


B Q UserProfileCartServlet 

- * void addUserShoppingCart(ltem) 

* void createUserProfile(UserCart) 

* void doGet(HttpServletRequest HttpServletResponse) 

■» void doPost(HttpServletRequest HttpServletResponse) 

<• String getParameter(HttpServletRe quest String, boolean, boolean, boolean. String) 

* void itemCreateToOutputPage(HttpServletRequest HttpServletResponse, UserCart Item) 
<• void performTask(HttpServletRequest HttpServletResponse) 

* void processLogin(HttpServletRequest HttpServletResponse, UserCart Item) 

* boolean retrieveUserProfile(String) 

* void userCreateToOutputPage(HttpServletRe quest HttpServletResponse, UserCart) 
Figure 211. U serP rofi leCartS ervl et M ethods L i sti n g 

The UserProfileCartServlet class manages the access to the user profile. It 
creates a user profile if it does not exist and displays the contents for an 
existing user profile. The content of the shopping cart of the profile is 
modifiable. Our class is a subclass of PageListServlet, which is a subclass of 
HttpServlet that can invokej SPs (Figure 212). 


import javax. servlet.*; 
import javax. servlet. http.*; 

import com. ibm. servlet. personal izati on. userprofile.*; 

public class UserProfileCartServlet extends com. ibm. servlet. PageListServlet 
implements java. io. Serializable 

{ 

private UserProfile profile = null; 

} 


Figure 212. UserProfileCartServlet Class Declaration 

The addU serShoppi ngCart method adds the shopping cart object into the 
UserProfile (Figure 213). 
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public void addllserShoppingCart(Item item) 

throws java. i o.NotSerial i zabl eException { 

profile. addShoppi ngCart(i tern) ; 

} 


Figure 213. UserProfileCartServlet addU serS hoppi ngCart Method 

Note: I n our simple example, the shopping cart contains only one item. To 
make this a true shopping cart, you can pass a Vector that contains multiple 
objects. Any collection type of object can be placed here as long as all of the 
collection objects and the objects inside of them a re Serializable 

The createUserProfile method checks to see if the profi le already exists under 
the specified UserName. If not, it will create and update the UserProfile 
fields. If there is a UserProfile under the same UserName it throws an 
exception (Figure 214). 


public void createUserProfi 1 e(UserCart userCart) throws java. larg. Exception { 
profile = UserProf i 1 e.addUserProfi 1 e(userCart.getUserName() ) ; 
i f ( profi 1 e ! = null) { 

profi 1 e. setFi rs tName( userCart .get Fi rstName() ) ; 
prof ile. set Last Name (userCart. get Last Name ()) ; 
profi 1 e. set Language (userCart .get Language () ) ; 


else { 

throw new java.lang.Exception("UserName: 
+ " al ready exi sts") ; 


+ userCart. getUserName() 


Figure 214. UserProfileCartServlet.createUserProfile 


The doGdt method processes incoming HTTP GET requests (Figure 215). 


public void doGet(javax. servlet. http. HttpServl etRequest request, 

javax. servlet. http. HttpServl etResponse response) { 

performTask(request, response); 

} 


Figure 215. U serP rofi leCartS ervl et doGet M ethod 
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The doPost method processes incoming HTTP GET requests (Figure 216). 


public void doPost(javax. servlet. http. HttpServl etRequest request, 

javax. servlet. http. HttpServl etResponse response) { 
performTask(request, response); 

) 


Figure 216. UserProfileCartServlet doPost Method 

The getParameter method reads a parameter fromtheHTML orj SP fileand 
returns it as a string (Figure 217). 


public String getParameter(HttpServl etRequest request. 

String parameterName, 

boolean checkRequestParameters, 

boolean checklni tParameters , 

boolean i sParameterRequi red, 

defaul tVal ue) throws java. lang. Exception { 

java.lang.String[] parameterVal ues = null; 
java. lang. String paramValue = null; 

// Get the parameter from the request object if necessary, 
if (checkRequestParameters) { 

parameterValues = request. getParameterValues(parameterName) ; 
if (parameterValues != null) 

paramValue = parameterVal ues [0] ; 

} 

// Get the parameter from the servlet init parameters if 

// it was not in the request parameter. 

if ( (checklni tParameters) && (paramValue == null) ) 

paramValue = getServletConfig() .getlnitParameter(parameterName) ; 

// Throw exception if the parameter was not found but was required 
if ( (i sParameterRequi red) && (paramValue == null) ) 
throw new Exceptionp'Parameter" + parameterName + 

"was not specified."); 

// Set the return to the default value if the parameter was not found 
if (paramValue == null) paramValue = defaul tVal ue; 

return paramValue; 

) 


Figure 217. UserProfileCartServlet getParameter Method 
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The itemCreateToOutputPage method takes care of creating an item and 
adding it to the UserProfiles shopping cart. Once the update is done 
successfully, the output page(aj SP) iscalled todisplay UserProfileand its 
shopping cart content (Figure 218). This method is invoked when the Submit 
button from the ItemCreate page (Figure 226 on page 229) is clicked. 


public void i temCreateToOutputPage( 

HttpServl etRequest request, 

HttpServl etResponse response, 

UserCart userCart , 

Item itemlrfo) throws java. lang. Exception { 

UserCart tempCart = null; 

javax. servlet. http. HttpSession session = null; 
session = request. getSessi on (true) ; 

itemInfo.setItem(getParameter(request,"item", true, true, true, null)); 
itemInfo.setPrice(getParameter(request, "price", true, true, true, null)); 
tempCart = (UserCart)session.getValue("userCart") ; 

userCart. setFi rstName (tempCart. getFi rstNameO) ; 
userCart .setLastName (tempCart .get LastNameO ) ; 
userCart .setUserName (tempCart .getUserName() ) ; 
userCart .set Language (tempCart .get Language () ) ; 

addUserShoppingCart(itemlnfo) ; 

//default output page 

cal 1 Page(getPageNameFromRequest(request) , request, response); 

) 


Figure 218. UserProfileCartServlet itemCreateT oOutputPage M ethod 

The performTask method processes incoming requests for information. It 
checks from which page the request has been made and, based on that 
information, calls the appropriate method (Figure 219). I n case any of the 
methods called throw an exception, the handleError method is called, which 
in turn launches the error output page (Figure 233 on page 234). 
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public void performTask(HttpServletRequest request, 

HttpServl etResponse response) { 


try 


// instantiate the bean and store it in the request so it can be accessed by 

// the called page 

UserCart userProfi leCart = null; 

Item i temlnfo .= nul 1 ; 

String aPageName * new StringO; 


itemlnfo = (Item) java. beans. Beans. instanti ate(getCl ass () .getCl assLoader() , 

"i tso.wasdb. userprofi 1 e. Item") ; 


userProfi 1 eCart = (UserCart) 

j a va. beans. Beans. i nstantiate(getClass() . get C 1 ass Loader () , 
"i tso.wasdb. userprofi 1 e. UserCart") ; 

// store the bean in the request so it can be accessed 
// by pages which are accessed with callPage() 


setRequestAttri bute(" userProfi 1 eCart" , userProfi 1 eCart, request) ; 
setRequestAttri bute ( " i temlnfo" , itemlnfo, request); 


aPageName = getParameter(request, "PageName", true, true, true, null); 


if(aPageName.compareTo("ItemCreate") == 0) { 

itemCreateToOutputPage(request, response, userProfi 1 eCart, itemlnfo); 

} 

else if (aPageName. compareTo ("UserOutput") == 0) { 
cal 1 Page("ItemCreate" , request, response); 


else if (aPageName. compareTo ("UserCreate") == 0) { 

us erCreateToOut put Page (request, response, userProfi 1 eCart) ; 

} 

else { //request is from "Login" page 

userProfi 1 eCart .setUserName(getParameter(request, "userName", true, true, 

true, null)); 

processLogin(request, response, userProfi 1 eCart , itemlnfo); 


catch (Exception theExcepti on) 

( 

handl eError(request, response, theExcepti on) ; 
try{ 

java.io.PrintWriter out = response. getWri ter() ; 

out.println(" <br>") ; 

out.println("Exception occurred: " + theException + "<br>"); 

out.println(" <p><br>") ; 

theException. pri ntStackTrace(out) ; 


} 

catch(java. i o. IOExcepti on e) { 

System. out. pri ntl n (" IOExcepti on occurred: " + e) ; 
}//endcatch 
}//endcatch 

} 


Figure 219. UserProfileCartServlet performTask M&hod 
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The processLogin method (Figure 220) is called from the Login Page (Figure 
229 on page 231). Depending on whether the U serP rofi I e with the UserName 
already exists or not, it calls the UserOutput page (Figure 231 on page 233) 
or UserCreate page (Figure 230 on page 232). 


public void processLogin(HttpServletRequest request, 

HttpServl etResponse response, 

UserCart userCart , 

Item itemlnfo) throws java. lang. Exception! 

boolean isFound = false; 

Item templtem = null; 

javax. servlet. http. HttpSession session = request. getSessi on (true) ; 
isFound = retrieveUserProfile(userCart.getUserName()) ; 

if( isFound == true ) { // if the UserProfile already exists 
userCart .set Fi rst Name (prof i 1 e . get Fi rstName() ) ; 
userCart. set Las tName (prof i le. get Last Name ()) ; 
userCart. setUserName (prof i le. get UserName ()) ; 
userCart. set Language (prof i le. get Language ()) ; 
session . putVal ue( " userCart" .userCart) ; 
templtem = (Item)profile.retrieveShoppingCart() ; 

if(templtem != null) { //make sure there is an object in shopping cart 
i temlnfo. set I tern (temp I tern. get I tern () ) ; 
itemlnfo. set Price (templtem. get Price()) ; 

) 

//default output page 

cal 1 Page(getPageNameFromRequest(request) , request, response); 

}//endif 

else { // UserCreate page is called if it's a new user 
cal 1 Page("UserCreate" , request, response); 

}//endelse 

) 


Figure 220. UserProfileCartServlet processLogin M&hod 

The retri evdU serP rofi I e method attempts to retrieve a UserProfile based on 
the userName passed. If the U serP rofi I e does not exist, it returns false, 
otherwise it returns true (Figure 221). 
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public boolean retrieveUserProfile(String userName) { 
boolean isFound = true; 

profile = UserProfile. retrieveUserProfileByUserName(userName) ; 

if( profile == null) { 
isFound = false; 

} 

return isFound; 

} 


Figure 221. UserProfileCartServlet retrieveUserProfile Method 

The userCreateT oOutputPage method (Figure 222) is called from the 
U serCreate page (Figure 230 on page 232), it takes the parameters passed for 
the UserProfi I e fields and then creates the UserProfile. It also stores the new 
information of the UserProfile inside an HttpSession object so it can be 
accessed from other pages (see the itemCreateT oOutputPage method in 
Figure 218 on page 224). 


public void userCreateToOutputPage( HttpServl etRequest request, 
HttpServl etResponse response, 

UserCart userCart) throws java. lang. Exception { 

//create if it's not already created 

javax. servlet. http. HttpSession session = request. getSessi on (true) ; 
userCart.setUserName( 

getParameter(request, "userName", true, true, true, null)); 
userCart. set Fi rst Name ( 

getParameter(request, "firstName", true, true, true, null)); 
userCart. set Las tName( 

getParameter(request, "lastName", true, true, true, null)); 
userCart .set Language ( 

getParameter(request, "language", true, true, true, null)); 

session .putVal ue(" userCart" .userCart) ; 
createUserProfi 1 e (userCart) ; 

//default output page 

cal 1 Page(getPageNameFromRequest(request) , request, response); 


Figure 222. UserProfileCartServlet userCreateT oOutputPage M ethod 
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Output Result 

I n this section we will step through a flow of HTM L pages to demonstrate the 
creation or retrieval of a user profile starting from the login page. 

TheLogin page (Figure 223) isthefirst page displayed. After entering the 
user name, control passes to the next page, depending on whether a user 
profile for the user name exists or not. 



F i gure 223. U serP rofi le Login Page 

If the user name entered in theLogin page does not exist in the UserProfile 
table, the UserCreate page (Figure 224) is called. This page prompts you to 
create a new UserProfile. 


Create a New User 


Enter the user parameters below and click Submit. A user profile with the specified properties 

will be created if it does not already exist. Otherwise, you will receive 

a duplicate user 

message. 


User Name: |socrates| 


First Name: | 


Last Name: | 


Language: | 


Submit | Reset | 



F i gure 224. U serP rofi I e U serC reate Page 
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Once the user profile is created, the result is displayed in the default output 
page (Figure 225). 


User Information 

UserName : Socrates 

FirstName: Steve 
LastName : Lee 
Language : English 

Item Detail 

Item : 

Price: 

To overwrite the existing item or create a new one press: New Item 


Figure 225. UserProfileDefault OutputP age After User Registration 

You can create a new item to be added to the shopping cart part of the 
UserProfile. The shopping cart only takes one object. A new object always 
overwrites the old one. This is done using the ItemCreate page (Figure 226). 


Please complete the form and click on Submit. 

Item [look 
Price |l2 .27 

Submit | 

F i gure 226. UserProfi I e I temC reate Page 

After submitting the item, the default output page with the newly created 
item is displayed (Figure 227). 
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User Information 

UserName : Socrates 
FirstName: Steve 
LastName : Lee 
Language : English 

Item Detail 

Item : Book 
Price: 12.27 

To overwrite the existing item or create a new one press: New Item | 


Figure 227. U serP rofi I e Default Output Page After Item Creation 


XML, HTML, and JSP Files 

I n this section we list all the source files that control the servlet and the 
HTM L output. The servlet knows from which page a request is initiated by 
looking at the valueof the hidden field PageName. This field is set in all J SP 
and HTM L files. 

XML Servlet Configuration File 

TheUserProfileCartServlet. servlet fi le (F igure 228) is an XML filewhich 
contains the definition for all of the pages called by cal I Page method. The 
pages listed in the servlet file are all of typ ej avaServer Pages. 
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<?xml version="1.0"?> 

<servl et> 

<page-l i st> 

<defaul t-page> 

<uri>/i tso/jsp/UserProfi leCartOutput Page. jsp</uri> 
</default-page> 

<error-page> 

<uri>/i tso/jsp/UserProfi 1 eCartErrorPage. jsp</uri> 
</error-page> 

<page> 

<uri>/i tso/jsp/UserProfi 1 eCreate. jsp</uri> 

<page-name>UserCreate</page-name> 

</page> 

<page> 

<uri>/i tso/jsp/ItemlrfoInputPage. jsp</uri> 

<page-name>ItemCreate</page-name> 

</page> 

</page-l i st> 

<code>i tso.wasdb. userprofi 1 e.UserProfi leCartServl et</code> 
<description></description> 

</servl et> 


Figure 228. UserProfi leCartServlet.Servlet Control File 

Login HTML File 

The UserProfileLogin.html file (Figure 229) is the first page displayed for the 
user login. 


<HTML><HEAD> <TITLE>Login </TITLE> </HEAD> <B0DY> 

<F0RM METH0D=P0ST 

ACTI 0N=" /servlet/it so. wasdb. userprofi le. UserProfi leCartServlet"> 

Please Input Your User Name: 

< I N PUT TYPE=H I DDEN NAME="PageName'' VALUE=" Logi n"> 

<TABLE BORDER=0 FRAME=NONE RULES=NONE ALIGN=LEFT WIDTH="50%" 

CELLPADDING="4" CELLSPACING="1"> 

<TR><TH ALIGN = " LEFT" WIDTH="5%"></TH> <TH ALIGN="LEFT" WIDTH= "45%"></TH> 
</TR> 

<TR><TD><INPUT TYPE=TEXT NAME="userName" ID="userName"> </TD> 

<TD>< INPUT TYPE=SUBMIT NAME="submi t" ID="submit" VALUE=" Logi n"></TD> 

</TR> 

</TABLE><br CLEAR=" LEFT"> 

</F0RM> </B0DY></HTML> 


Figure 229. UserProfileLogin.html File 
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JSP Files 

The UserProfileCreatejsp file (Figure 230) contains the entry fields for 
creating a new UserProfile. 


<HTML><HEAD> 

<TITLE>User Profile Create</TITLE> 

</HEAD><B0DY> 

<BEAN NAME="userProfileCart" TYPE="itso.wasdb. userprofile. UserCart" INTR0SPECT=N0 
CREATE=N0 SCOPE=REQUEST></BEAN> 

<form ACTION="/servl et/i tso.wasdb.userprofi 1 e.UserProfi 1 eCartServl et" METH0D="P0ST" 
ENCTYPE="appl i cati on/x-www-form-url encoded"> 

<1 N PUT TYPE="HIDDEN" NAME="PageName" VALUE="UserCreate"> 

<d i v al i gn="center"><center><p><font SIZE="4">Regi ster a New User</font></p> 
</center></di v><di v al ign="center"><center><tabl e B0RDER="0" WIDTH="85%"> 

<tr> 

<td WIDTH=" 100%">Enter the user parameters below and click Submit. A user profile 
with the specified properties will be created if it does not already exist. 
Otherwise, you will receive a duplicate user message. </td> 

</tr> 

<tr> <td WIDTH=" 100%"></td> </tr> 

</tabl e> 

</center></di v><di v al ign="center"><centerxtabl e B0RDER="0" CELLPADDING="4" 

C ELLSPACI NG= " 1 " WIDTH="50%" FRAME="NONE" RULES="NONE"> 

<tr> 

<tdxdiv al ign="right"><p>User Name: </td> 

<tdxinput TYPE="TEXT" NAME="userName" SIZE="25" ID="userName" 

VALUE=<INSERT BEAN="userProfi 1 eCart" PROPERTY="userName"x/INSERT»</td> 

</tr> 

<tr> 

<tdxdiv al ign="right"><p>Fi rst Name: </td> 

<tdxi nput TYPE="TEXT" NAME="firstName" SIZE="25" ID="firstName"x/td> 

</tr> 

<tr> 

<tdxdiv al ign="right"><p>Last Name: </td> 

ctdxinput TYPE="TEXT" NAME="lastName" SIZE="25" ID="lastName"x/td> 

</tr> 

<tr> 

<tr> 

<tdxdiv al i gn="ri ght"><p>Language: </td> 

<tdxinput TYPE="TEXT" NAME="language" S I ZE= "25 " ID="language"x/td> 

</tr> 

<tdx/td> 

<tdx/td> 

</tr> 

<tr> 

<td C0LSPAN="2"xdiv al ign="center"xcenter><p><input TYPE="SUBMIT" 
NAME="submit" 

VALUE="Submi t" ID="submit"> <input TYPE="RESET" NAME="reset" VALUE="Reset" 
ID="reset"> </td> 

</tr> 

</tabl e> 

</center></di v> 

</form> 

</BODYx/HTML> 


Figure 230. UserProfileCreatejsp File 
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Notice the BEAN tag that refers to the UserCart} avaBean. The/ NSERT tag 
retrieves the userName property from the bean. 

The UserProfileCartOutputPagejsp File (Figure 231) displays the content of 
the UserProfile, including the contents of its shopping cart. 


<HTML><HEAD> 

<TITLE>User Informati on</TITLE> 
</HEAD><B0DY> 


<H2>User Informati on<br> 


</H2> 

<BEAN NAME="userProfi leCart" TYPE="itso.wasdb. userprofile. UserCart" INTR0SPECT=N0 
CREATE=N0 SCOPE=REQUEST></BEAN> 

<b> UserName :</b> 

<INSERT BEAN="userProfi leCart" PR0PERTY=" userName "> </INSERT><BR> 
<b> Fi rstName:</b> 

<INSERT BEAN="userProfi leCart" PROPERTY="fi rstName"> </INSERT><BR> 
<b> LastName :</b> 

<INSERT BEAN="userProfi leCart" PROPERTY="lastName"> </INSERT><BR> 


<b> Language :</b> 

<INSERT BEAN="userProfi leCart" PROPERTY="language"> </INSERT><BR> 


<H2> 

<br>Item Detail 

<br> </H2> 

<BEAN NAME="itemInfo" TYPE="i tso.wasdb .userprofi 1 e. Item" INTR0SPECT=N0 CREATE=N0 
SCOPE=REQUEST></BEAN> 

<b> Item :</b> <INSERT BEAN="itemInfo" PROPERTY="i tem"></INSERT><BR> 

<b> Price:</b> <INSERT BEAN="itemInfo" PROPERTY="pri ce"></INSERT><BR> 

<form ACTION="/servl et/i tso.wasdb. userprofi 1 e. UserProfi 1 eCartServl et" METH0D="P0ST" 
ENCTYPE="appl i cati on/x-www-form-url encoded"> 

<input TYPE="HIDDEN" NAME="PageName" VALUE="UserOutput"> 


To overwrite the existing item or create a new one press: 

<input TYPE="SUBMIT" NAME="submi t" VALUE="New Item" ID="submit"> 
</form> 

</B0DY></HTML> 


Figure 231. UserProfileCartOutputPagejsp File 


I n thisj SP filethe userCart is defined in a BEAN tag and its property values 
are retrieved in INSERT tags. 

The I teml nfol nputPagejsp file (Figure 232) contains the entry fields for 
creating a new Item. 
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<HTML><HEAD> 

<TITLE></TITLE> 

</HEAD><BODY> 

<FORM METHOD=POST ACTION="/servl et/itso.wasdb.userprofi 1 e.UserProfi 1 eCartServl et"> 
Please complete the form and click on Submit. 

<input TYPE="HIDDEN" Name="PageName" VALUE=" ItemCreate"> 

<TABLE BORDERS FRAME=NONE RULES=NONE ALIGN=LEFT WIDTH="50%" CELLPADDING="4" 

CELLS PAC I NG= " 1 "> 

<TR><TH ALIGN="LEFT" WIDTH="5%"></TH> 

<TH ALIGN="LEFT" WIDTH="45%"></TH> 

</TR> 

<TR> 

<TD>Item</TD> 

<TD><INPUT TYPE=TEXT NAME="item" ID="item"></TD> 

</TR> 

<TR> 

<TD>Pri ce</TD> 

<TD><INPUT TYPE=TEXT NAME="price" ID="price"></TD> 

</TR> 

</TABLE> 

<BR CLEAR="LEFT"> 

<BR> 

<1 N PUT TYPE=SUBMIT NAME="submi t" ID="submit" VALUE="Submit"> 

</F0RM> 

</B0DY></HTML> 


Figure 232. Iteml nfd nputPagejsp File 

The U serProfi leCartE rrorPagejsp file (Figure 233) contains a message for 
the error. The detail of the error is loaded into the page dynamically (Figure 
219 on page 225). 


<HTML><HEAD><TITLE>User Profile Error</TITLE></HEAD><BODY> 
<h3>An error has occurred using User Prof i 1 e .</h3> 
</B0DY></HTML> 


Figure 233. U serProfi leCartE rrorPagejsp File 
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Testing the User Profile Sample in VisualAge for Java 

The user profile sample will fail in the VisualAge for J ava test environment 
because no database information has been prepared for storing user profiles. 

Setting up the Database 

To activate the user profi le function we have to change a properties file of the 
WebSphere Test Environment: 

c:\IBMVJava\ide\project_resources\IBM WebSphere Test Envi ronment\ 
properti es\server\servl et\servletservice\ userprofi 1 e.properti es 

Change the properties files as shown in Figure 234. 


# @(#)userprofile. properties 

# 

# User Profiles Configuration Screen 

# 

ncf . userprofi 1 e=true 

ncf . userprofi 1 e.db. used=db2 

ncf .userprofi le.db. jdbcdriver=C0M.ibm.db2.jdbc.app.DB2Driver 

ncf . userprofi 1 e.db. instance=ITSOWDB 

ncf . userprofi le.db. owner=ITS0 

ncf . userprofi 1 e.tabl ename=userprofi 1 e 

ncf . userprofi 1 e.useri d=ITS0 

ncf . userprofi le.password=itso 

ncf.userprofile.cl assname=com.i bm.servl et. personal i zati on .userprofi le. UserProfi 1 e 
# 

# Properties for connection manager initialization 
ncf . userprofi 1 e .connmgr. pool name=JdbcDb2 
ncf . userprofi 1 e. connmgr. wait retry=fal se 

F i gure 234. User P rofi I es P roperti es File 

Source Files 

Thesource files must be placed into appropriate directories: 

□ UserProfileCartServlet.servlet: store in the project resources directory of 
VisualAge for J ava: 

c:\IBMVJava\ide\project_resources\ITSO SG24 547 l\i tso\wasdb\userprof i 1 e 

□ UserProfileLogin.html : store in a subdirectory of the HTM L directory: 

c:\Program Files\IBM HTTP Server\htdocs\itso 

□ J SP Files: store in a subdirectory of the HTM L directory: 

c:\Program Files\IBM HTTP Server\htdocs\itso\jsp 
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Run the User Profile Sample 

Start the WebSphere Test Environment and open a browser with the URL: 
http :// 127. 0. 0.1: 8080/ itso/UserProf ileLogin.html 

The first access to a user profile creates tbelTSO.USERPROFILE table in 
thelTSOWDB database. 

The output of the user profilesampleshould match thedecription in "Output 
Result" on page 228. 


Running the User Profile Sample in WebSphere 

Configure WebSphere as described in "Configuration" on page 214. Deploy 
the beans and the servlet to WebSphere: 

c:\WebSphere\AppServer\servl ets 

The source files must be placed into appropriate directories: 

□ UserProfileCartServlet.servlet: store i n the servlets directory of 
WebSphere, together with the servlet code and the beans. 

c:\WebSphere\AppServer\servl ets\i tso\wasdb\userprofi 1 e 

□ UserProfileLogin.html : store in a subdirectory of the HTM L directory: 

c:\Program Fi 1 es\ I BM HTTP Server\htdocs\itso 

□ J SP Files: store in a subdirectory of the HTM L directory: 

c:\Program Fi 1 es\ I BM HTTP Server\htdocs\itso\jsp 

Open a browser with the URL: 

http://hostname/i tso/UserProfi 1 eLogi n .html 

The first access to a user profile creates thelTSO.USERPROFILE table in 
thelTSOWDB database on the WebSphere server machine. 

The output of the user profilesampleshould match the description in 
"Output Result" on page 228. 
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13 WebSphere Security 
and the LDAP 
Directory 

In thischapter wediscuss securing access to resources using a directory 
service. 
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Introduction 


A directory service is a combination of: 

□ An information repository: A database is often used to store location 
information and other details about resources such as users, printers, file 
servers, and application servers. 

□ An access method: The Lightweight Directory Access Protocol (LDAP) 
or other access methods can be used to communicate with directory 
service components. 

□ Related services: A directory service provides facilities for querying, 
manipulating, and authenticating the information in its database. 

You might already have set up a directory service product to hold global 
security data that many other software applications, such as an application 
server and your Web server, can use to authenticate users who try to access 
resources. 

WebSphere supports the use of three different directory service types: 

□ Domino 4.6 

□ N etscape Di rectory Server 

□ e-Network I BM Suite 

The security access to the directory service is provided through ACL, access 
control list, in WebSphere. When using directory service for security, 
WebSphere acts as the client of the directory service. The setup for the 
resource security is donethrough an ACL. Resources such as servlets are 
assigned an ACL, and based on the permissions provided through the ACL, 
the level of access is provided. 


Access Control Lists 

The ACL associated with a resource specifies which users or groups in a 
real m are permitted to access the resource. ACLs, real ms, and resources have 
the following relationships (Figure 235): 

□ A realm can contain many ACLs. 

□ A realm can contain many resources. 

□ An ACL can belong to only one realm. 

□ A resource is associated with only one ACL. 

□ A resource can belong to only one realm. 

□ An ACL can be associated with many resources. 
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m = many 

Figure 235. Relationships Between Realm , ACL, and Resource 

I n some cases, a service does not requi re its customers to be in an access 
control list. For example, many Web page (HTTP) services make their 
documents availableto all users without requiring them to register in an 
access control list (ACL). 


Realms 


A realm is a database of users, groups, and ACLs. A user must be defined in a 
realm in order to access any resources belonging to that realm. 

A user can belong to several realms, but a user I D cannot be duplicated 
within a realm. For example, the user amy can belong to the realms 
fileRealm and anyRealm. Each of those realms can contain only one user 
named amy. The user amy can be given different permissions for different 
resources in each realm. 

A person, such as Amy might havedifferent user I Ds in each realm. For 
example, she might be amy in thefileRealm, but is amy2 in the anyRealm 
because there is already a person in anyRealm using the user I D amy 

IBM WebSphere Application Server ships with some pre-established realms: 

□ The defaultRealm defines how users may access resources defined 
locally. You can establish ACLs to determine which users and groups have 
access to which resources. 

□ The NT realm and the UNIX realm define how users with accounts on 
your operating systems may access WebSphere resources. Users defined 
in theoperating system are shared by WebSphere and continue to exist 
for as long as they exist in the underlying system. The application server 
manager interface lets you view this realm; to change it, you must use the 
facilities provided by your operating system. Currently, WebSpherecan 
share users, but not groups, defined in theoperating system. 
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□ The servletMgrRealm defines how servlets may access resources 
defined remotely, such as remotely loaded servlets. The servlet ACL is the 
only access control list in this realm. When a remotely loaded, 
digitally-signed servlet tries to access a protected resource, the digital 
certificate in the servlet is compared with digital certificates associated 
with users in the servletMgrRealm. The servletACL decides whether 
permission is granted or denied. 

For example, suppose the digital certificate of userX is packaged in the 
anyServlet.J AR file. If userX is added to the servletMgrRealm, any servlet 
containing the same digital certificate as that of userX (found in 
anyServlet.J AR) may execute and access resources granted to userX. 

□ Finally, the IdapRealm (Figure 240 on page 244) is displayed if you have 
a directory service enabled on the Directory M anagement page (Figure 
236 on page 241) of the WebSphere Application Server Administration. 

Users and groups defined in the directory service are shared by WebSphere 
and continue to exist for as long as they exist in the directory service or until 
you disable directory management support. The application server manager 
interface lets you view this realm; to change it, you must use the facilities the 
LDAP server provides. 

For more information about LDAP, directory services, and the IdapRealm, see 
Using a directory service with Application Server in the WebSphere online 
documentation. Also refer toth eLDAP Implementation Cookbook, 
SG24-5110. 


Resources 


Resources are the valuable items accessible by the Web server: 

□ HTM L files and directories, such as http://www.anycompary.com 

□ Other files and directories, such as ftp://www.anycompany.com 

□ Web applications: J ava servlets or CGI programs 

and by the WebSphere Application Server: 

□ J ava servlets 

□ Connections, sockets, files, and other resources used by servlets 

□ Custom servlets that enable access to enterprise resources and 
applications (such as databases) 

Each resource can be protected by establishing a single ACL for that 
resource, in a single realm. The ACL specifies which users or groups are 
al lowed to access or modify the resource. 
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For each resource to protect, you specify: 

□ An access control list (ACL)— a list defining who can use the resource 

□ A security realm— a logical security area the resource belongs to 

□ An authentication scheme— a way to verify users who ask for the resource 

The relationship among these items will become apparent shortly 


Setup and Configuration 

You must have installed a directory server and user I Ds created for the 
directory server prior to starting the setup on WebSphere. 

Netscape Directory Server 4.0 was used to provide security access to our 
resources, namely servlets. 

The following arethesteps involved in setup and configuration of security 
through directory service. 

□ Start the WebSphere Administration panel, see "WebSphere 

Configuration" on page 6. Select Directory M anagement (Figure 236). 


WebSphe,e Application Serve. ) I D j rectory Management 


D Introduction 
▼O Setup 

( 2 ) Administration 
O Connection Management 
0 Directory Management 
0 Java Engine 
0 Session Tracking 
0 User Profile 
0 Virtual Hosts 

► O Servlets 

► O Enterprise Java Services 

Security 
0 Users 
0 Groups 

0 Access Control Lists 
0 Resources 

► O Server Execution Analysis 
0 Log Off 


<] Ready 


Configure 




sonoma. almaden. ibm. com 


Enable Directory? |Yes| No 
Directory Type? | netscape 
Host Name: 

Port: 

Base DN: 

Bind DN (optional): 


Bind Password (optional): 


389 


o=almaden. ibm. com 


Figure 236. WebSphere Administration S&up for Di rectory M anagement 

□ From the WebSphere Administration main menu, select the Access 
Control List and select the IdapRealm and click on the Add button (Figure 
237). 
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Realm: [idapRealm 3] 


Add 


Defined Access Control Lists 


Rerriova 


Permission Principal 


Action Allowed? 


d 


d 

d 


d 


Figure 237. WebSphere Access Control List Main Panel 
□ From the Add ACL panel, input the N ew ACL Name (Figure 238). 


. 

Add ACL 

Ml 



New ACL Name: |lTS0 


Add | Cancel | 


Warning: Applet Window 


Figure 238. Adding a New Access Control List 

□ From the Access Control List main panel (Figure 237) select the newly 
created ACL and click on the lower Add button to add permissions to the 
new ACL. Select the type of permissions you want to give to a user or a 
group (Figure 239). As you may have noticed, the user I Ds and group I Ds 
are the same as the ones you have specified in the directory service. 
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Note: To enable access to the servlets, you should Assign Permission for Files 
and Folders. Files and Folders refers to local directories and files, including 
servlets. Servlets refers to remotely loaded servlets. If you are unsure which 
to choose, Files and Folders is the appropriate choice in most cases. 



Figure 239. Add Permission to ACL 


□ At this point you have specified your ACL, and the ACL panel displays 
information based on the choices you made in the Add Permission to ACL 
panel (Figure 240). 
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Add 


Add 


Realm: |ldapRealm ~^| 


Remove 


Defined Access Control Lists 




ITSO 


J 


Remove 


Permission Principal 

Action Allowed? 

J 

0 Users 


0- JSmith 


|— Get 

Yes 


| Put 

Yes 


j— Post 

Yes 


L - Delete 

Yes 


O Groups 



O Hosts 


J 


Figure 240. WebSphere Access Control List Main Panel with New ACL 

□ Next is to set up access to your resources based on the newly created ACL. 
Select Resources fromthe WebSphere Administration main menu. From 
the Resources panel select the IdapRealm. Click on the Add button to add 
a resource to the desired ACL (Figure 241). 


Realm: [idapReaim 


Add 


Resource 

Type 

Scheme 

ACL 


Ren 


J 


F i gure 241 . WebSphere R esources Securi ty S etup 
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□ From the Protect a Resource dialog, select a Scheme^ ACL, and a Resource 
to Protect, and click on the OK button (Figure 242). 


Protect a Resource 


Realm: IdapRealm 

Scheme: <*■ Basic Digest SSL 
ACL: | ITSO jj 
i— Resource to Protect 
C Pathname: 

<*■ Sen/let: |DB2ConnectionMg r 

OK | Apply | Cancel | Help | 

Warning: Applet Window 

Figure242. Protecta Resource using Directory Service through ACL 

After performing these steps you have specified your resource security access 
based on the setting in the directory service (Figure 243). 


Realm: jldapRealm ~^| 


Add 


Modify 


Resource 

Type 

Scheme 

ACL 

D B 2ConnectionM gr 

Servlet 

Basic 

ITSO 



J 


Remove 


Figure243. ResourcePanel after Adding a Resourceto beProtected 
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14 Using SQLJ to 
Access a Database 


SQLJ is a method of accessing database information using embedded SQL in 
J ava code. I n this chapter we will discuss what you need in order to use SQLJ 
and givea simple example of using SQLJ with WebSphereand DB2. 

Note: To use the SQLJ functionality, you must install fixpack 8 for DB 2 
Version 5. 
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What is SQLJ? 


SQLJ allowsj ava programmers to create static SQL forj ava applications as 
well as the dynamic SQL which traditional J DBC drivers provide. The use of 
static SQL allows all authority, syntax, access strategy, and logic checking to 
be done at SQL compile time. This unique ability provides performance 
i ncreases for a ppl i cat i ons t hat repeated lyusethesameSQL. 

SQLJ was developed as a combined effort by Oracle, Tandem, and I BM to add 
static SQL toj DBC. It has recently become an ANSI standard. The 
specification consists of three parts: 

□ Part 0 specifies the SQLJ language syntax and semantics for embedded 
SQL statements in aj ava application. 

□ Part 1 specifies extensions that define: 

• Installation of J ava classes in an SQL database 

• I nvocation of static methods as stored procedures 

□ Part 2 specifies extensions for accessing J ava classes as SQL distinct 
types. 

Most database vendors have implemented part 0 of this plan, but the goal is 
to gradually introduce the SQLJ technology into the products. We focus only 
on part 0 in this book. 


SQLJ and VisualAge for Java 

Unfortunately, VisualAge for J ava 2.0 does not support SQLJ . SQLJ 
operability is scheduled for Version 3, which should be available in the third 
quarter of 1999. 

VisualAge for J ava Version 2 cannot be used with SQLJ because VisualAge 
does not recognize the precompiler directives that SQLJ uses before its 
translation. This implies that the embedded SQL statements and other SQLJ 
resources will cause errors within VisualAge for J ava. 

This will cause some development slowdown, because you cannot use the 
WebSphereTest Environment and the VisualAge for J ava debugger. 
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SQLJ Translators, Input, and Output 

To compile J ava code with embedded SQLJ , you must put your code through 
a translator that will comment out and preprocess the SQLJ code so that a 
normal J ava compiler can successfully compile the code. 

The naming convention for SQLJ states that all J ava files with embedded 
SQLJ should have an extension of .sqlj before they are translated. The SQLJ 
translator is used totranslat e.sqlj files into .java files. It comments out all of 
the SQLJ code and replaces it with the proper J ava code used to implement 
the static SQL. 

When this translation occurs, J ava classes are created for the SQLJ iterators. 
Iterators are cursors that are used to store the results of the embedded SQL 
query. Because the result sets can have different numbers of columns and 
column types, a separate iterator must be created for each unique result set. 
You define a cursor to parse a result set using embedded SQL that is later 
interpreted by the translator. 

A class and a serialized file are also created for the query profile. This profile 
maintains the data used to keep the SQL static. 


Updating Serialized Profiles 

I nstead of having to rebuild information as dynamic SQL does, the serialized 
profile stores the information necessary to maketheSQL execution perform 
as quick as possible. The serialization filestores the bind information used to 
access the database. 

This profilecan be customized by running it through a customizer which 
connects to the database and updates the information stored regarding 
accessing your data. This customizer is found in the same directory as the 
translator. For DB2 the customizer is called db2profc.exe. It has the following 
usage: 

db2profc -user=<user> -password=<password> url =<database url> 

<profile rame>.ser 

You should customize the profile when the tables significantly change in 
volume. Failure to do so can cause inefficient access methods to be used to 
access the data. This is important, considering that performance is the main 
point of using static SQL files. 
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DB2 Resources for SQLJ 

For applications written using SQLJ towork properly, certain resources must 
be available. It is imperative that you include the foil owing files in your class 
path. These files must be in the WebSphere cl ass path as well. 

c:\sqlli b\java\db2java.zip 
c:\sqll ib\java\runtime.zip 
c:\sqlli b\java\sql j . z i p 

The sqlj.zip file is included with the DB2 Software Developer's Kit. It places 
the zip file in the same directory as other DB2 J ava resources. 

SQLJ is implemented using a J DBC connection to the database on Windows 
NT. To execute the SQL, you must first create a connection and a connection 
context as shown in our example. 


Using the SQLJ Translator with DB2 

With the installation of DB2 Software Developer's Kit, an executable named 
sqlj.exe is placed into the c/.i sqllib\ bin directory (where sqllib is the DB2 
installation directory). This file is the SQLJ translator. 

The SQLJ command has the format: 

sqlj <Java file name with SQLJ> 

The output file of type. java can be used by anyj ava translator and can be 
compiled normally. The SQLJ translator, by default, automatically compiles 
the output file and creates a serialized profile. The translator does not catch 
errors in thej ava source file, so make sure the file is syntactically correct. 


Employees in Department Example 

We use our example of finding all the employees in a specific department. We 
implement this example using a servlet and a bean. Theservlet contains all 
thej ava code to communicate with the bean. The bean controls the retrieval 
and displaying of the data. 
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Servlet 


The SqljServ servlet (Figure 244) contains noSQLJ code, therefore it is not 
run through the SQLJ translator. The servlet code invokes methods that 
contain SQLJ through the SQLJ ServBean. 


package itso.wasdb.sql j; 

import java.io.*; 
import java.sql .*; 
import javax. servlet.*; 
import javax. servlet. http.*; 

public class SqljServ extends HttpServlet{ 

public void doGet(HttpServletRequest req, HttpServl etResponse res) { 
PrintWriter out = null; 

String drv = "C0M.ibm.db2.jdbc.app.DB2Driver"; 

String dep = "A00"; 

SqljServBean sqljBean = new Sql jServBean() ; 
try { 

out = res.getWriter() ; 
out.pri ntl n("<HTML><BODY>") ; 

Class. forName(drv) .newlnstance() ; 

sql j Bean. setUserID("itso" ) ; 

sql jBean.setPassword("itso") ; 

sql jBean.setURL("jdbc:db2:i tsowdb") ; 

sql j Bean. startConnection() ; 

sql jBean.executeSQLJ(out, dep); 

) 

catch(SQLException sql Except) { sql Except. printStackTrace(out) ; 
catch (Exception except) { 
if( out != null ) { 
out.println(except) ; 
except . pri ntStackTrace(out) ; 

) 

else { 

System. out. pri ntl n (except) ; 
except. pri ntStackTrace() ; 

) 



F i gure 244. SQL] E xampl e S ervl et (S qljS erv.java) 
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Bean with SQLJ Code Before Translation 

The SQL) ServBean (Figure 245 and Figure 246) creates the connection, 
executes the SQL, and displays the result. These figures show the .sqlj code 
before translation. 


package itso.wasdb.sql j; 

import java.io.*; 
import java.sql .*; 
import sqlj .runtime.*; 
import sqlj .runtime. ref.*; 

#sql iterator DataCursor (String empno, String lastname, String workdept, 

Stri ng Sex) ; 

public class SqljServBean { 

// Instance variable for the URL property 
private String url=null; 

// Instance variable for the userlD property 
private String userID=null; 

// Instance variable for the password property 
private String password=nul 1 ; 

// Instance variable for Connection 
private Connection con=null; 

public void startConnection() throws SQLExcepti on{ 
try { 

con = DriverManager.getConnection(url , userlD, password); 
con.setAutoCommit(false) ; 

Defaul tContext ctx = new DefaultContext(con) ; 

Defaul tContext . set Defaul tContext (ctx) ; 

} catch (SQLExcepti on e) { 

System. out. println("Error: could not get a default context"); 
System. err. println(e) ; 

System. exit(l) ; 

} catch (Exception e) { 

System. out. println(e) ; 

} 

return; 



Figure 245. SQLJ Example Servlet Bean (Sqlj ServBean. sqlj) Part 1 


252 IBM WebSphere and VisualAge for Java Database Integration with DB2, Oracle, and SQL Server 




The startconn action method creates a connection to the database and creates 
a default context. SQLJ uses the default context connection in use with its 
serialized profile, so you must set one in your code. 


public void executeSQLJ(PrintWriter out, String dep) throws SQLException 

{ 

DataCursor cursorl; 
long countl = 0; 

// retrieve data from the database 

System. out. println("Retrieve some data from the database..."); 

#sql cursorl = { SELECT empno, lastname, workdept, sex from itso. employee 
where WORKDEPT = :dep }; 

// retrieve number of employees in the department 

#sql {SELECT count(*) into :countl from employee where workdept = :dep }; 
try { 

outputlnfo (cursorl , countl, out); 

} catch (SQLException hmmm) { throw hmmm;} 


public void outputInfo(DataCursor cs, long count, PrintWriter out) 
throws SQLException! 

out.println("<TABLE B0RDER=3 FRAME=ALL CE L LPADD I NG = 1 C EL LS PAC I NG= 1 
C0LS=4>") ; 

out . pri ntl n ("<CAPTI0N ALIGN=T0P><b>UDB - " + count + 

" Employees in Department</b></CAPTION>") ; 
out.println("<TR>") ; 

out.println("<TH ALIGN=CENTER WIDTH=20%>Emp Number "); 
out.println("<TH ALIGN-CENTER WIDTH=20%>Last Name "); 
out.println("<TH ALIGN=CENTER WIDTH=20%>Dept Name "); 
out.println("<TH ALIGN=CENTER WIDTH=20%>Sex "); 

whi le(cs.next()) { 

out.print("<TR><TD ALIGN=CENTER>" + cs.empno()); 
out.print("<TD ALIGN=CENTER>" + cs.lastname()) ; 
out.print("<TD ALIGN=CENTER>" + cs.workdept()) ; 
out.print("<TD ALIGN=CENTER>" + cs.SexQ); 

} 

out . pri ntl n ("</TABLE>") ; 


Figure 246. SQLJ Example Servlet Bean (SqljServBean.sqlj) Part 2 
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The executes QLJ method contains the embedded SQL. It creates a cursor to 
store the result of the SQL query and returns the result set to the cursor. 


The output! nfo method displays the information contained inthecursor. It 
uses the PrintWriter class to write the results to the Web browser. You can 
see how simple it is to retrieve a data item from the result set by the use of 
the cursor methods. 


SQLJ Code After Translation 

TheSQLJ code in these listings performs multiple functions. Each is 
described here and thej ava code resulting from translation is shown. 

Iterator 

#sql iterator DataCursor (String empno, String lastname, String workdept. 

String Sex) 

This statement creates the iterator, or cursor, used to store the result set of 
the SQL query. Because the SQL can return varying columns and types, we 
need to define an iterator before including what kind of output to expect so it 
can properly store the information. The cursor data types and the data types 
returned from the SQL statement are compared and checked during the 
translation of the SQLJ code. 

I n Figure 247, we see the definition of the iterator. The SQLJ translator 
creates this code, which makes it extremely easy to manage the output of 
queries. You just call the method named after thecolumn to retrievethe 
information stored in that column. The rows aretraversed using the 
iterator's next method as shown in the output! nfo method (Figure 246 on 
page 253). 
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/*@1 i nei nfo:generated-code*//*@l i nei nfo: 10^1*/ 

j j •k'k'k'k'k'k'k'k'kick'k'k'k'k'k'k'k'k'k'k'k'kick'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kick'k'k'k'k'k'k'k 

// SQLJ iterator declaration: 

j j 'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 

class DataCursor 

extends sq 1 j . runtime. ref . Resol tSetlterlmpl 
implements sq 1 j . runtime. Namedlterator 
{ 

public DataCursor(sql j . runtime. prof i 1 e.RTResul tSet resultSet) 
throws java.sql .SQLExcepti on 

{ 

super(resultSet) ; 
empnoNdx = fi ndCol umn ("empno") ; 
lastnameNdx = findColumn("lastname'') ; 
workdeptNdx = findColumn("workdept") ; 

SexNdx = findColumn("Sex") ; 

} 

public String empno() 

throws java.sql .SQLExcepti on 

{ 

return resultSet. getStri ng(empnoNdx) ; 

} 

private int empnoNdx; 
public String lastname() 
throws java.sql .SQLExcepti on 

{ 

return resultSet. getString(lastnameNdx) ; 

} 

private int lastnameNdx; 
public String workdept() 

throws java.sql .SQLExcepti on 

{ 

return resultSet. getString(workdeptNdx) ; 

} 

private int workdeptNdx; 
publ ic String Sex() 

throws java.sql .SQLExcepti on 

{ 

return resultSet. getString(SexNdx) ; 

} 

private int SexNdx; 

} 

j j 'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 

/*@1 i nei nfo:user-code*//*@l i nei nfo: 10^85*/ 


Figure 247. SQLJ Code after Translation: Iterator Class Definition 
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Select Statement with Result Set 

#sql cursorl = { SELECT empno, lastname, workdept, sex from itso. employee 
where WORKDEPT = :dep }; 

This select statement is embedded SQL codethat uses a host variable ( :dep ). 
You can see how simple it is to use the SQL and return the result intothe 
iterator. Figure 248 shows the translated SQLJ code. It is challenging to 
understand this code, but notice the use of the connection context. This is 
why it is necessary to create a default connection context when you create 
your initial connection to the database. Also notice how the code uses the 
ProfileKeys. ProfileKeys are an index to all the profiles used in the 
application and are stored in the serialized files that allow SQLJ to be static. 


j J •kick'k'k'k'k'k'k'k'k'k'k'k'k'k'kickickickick'kick'k'k'k'k'k'k'k'k'k'k'k'k'k'kick'kick'k'k'k'k'k'k'k'k'k'k'k'k'k 

// #sql cursorl = { SELECT empno, lastname, workdept, sex from itso. employee 
where WORKDEPT = :dep }; 

j j 'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 
{ 

sqlj .runtime. ConnectionContext sJT_connCtx = 

sql j .run time. ref .Defaul tContext.getDefaul tContext() ; 
if ( sJT_connCtx == null) 

sqlj. run time. error. Runt imeRef Errors .rai se_NULL_CONN_CTX() ; 

sql j .runtime. Executi onContext sJT_execCtx = 

sJT_connCtx. get Executi onContext () ; 

if ( sJT_execCtx == null) 

sqlj. run time. error. Runt imeRef Errors .rai se_NULL_EXEC_CTX() ; 

String sJT_l = dep; 

sql j . runtime. profi 1 e.RTStatement sJT_stmt = 

sJT_execCtx. regi sterStatement ( sJT_connCtx, 

i t so. wasdb. sql j .Sql jServBean_SJ Profi 1 eKeys. get Key (0) , 0) ; 
try 
{ 

sJT_stmt.setString(l, sJT_l); 

sql j .runtime. prof i 1 e. RTResul tSet sJT_result = 

sJT_execCtx.executeQuery() ; 

cursorl = new DataCursor( sJT_result); 

} 

f i nal ly 

{ 

sJT_execCtx. rel easeStatement() ; 

} 

} 

J J 'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 

/*@1 ineinfo: user-code*//*@lineinfo: 47 / T00*/ 


Figure 248. SQLJ Codeafter Translation: SimpleSelect Statement 
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Select Statement without Result Set 

#sql { SELECT court(*) into :countl from employee where workdept = :dep }; 

This statement does not return a result set, so it does not require an iterator. 
I nstead, this set simply counts the number of elements in the result and 
stores that number in a host variable (icountl). Figure 249 shows the 
translation of this statement. 


J I ************************************************************ 

// #sql { SELECT count(*) from employee where workdept = :dep }; 

J J ************************************************************ 

{ 

sql j .runtime. prof i 1 e.RTResul tSet sJT_rtRs; 

sql j .runtime. Connecti onContext sJT_connCtx = 

sql j .runtime. ref .Defaul t Context .getDefaul tContext () ; 
if ( sJT_connCtx == null) 

sql j .runtime. error. Runt imeRef Errors .rai se_NULL_CONN_CTX() ; 

sql j .runtime. ExecutionContext sJT_execCtx = sJT_connCtx.getExecutionContext() ; 

if ( sJT_execCtx == null) 

sql j . runtime. error. Runt imeRef Errors .rai se_NULL_EXEC_CTX() ; 

String sJT_l = dep; 

sql j .runtime, profi 1 e.RTStatement sJT_stmt =. 

sJT_execCtx.regi sterStatement ( sJT_connCtx, 

i tso.wasdb.sql j .Sql jServBean_SJ Prof i 1 eKeys.getKey (0) , 1) ; 

try { 

sJT_stmt.setString(l, sJT_l); 

sql j .runtime. prof i 1 e.RTResul tSet sJT_result = sJT_execCtx.executeQuery () ; 

sJT_rtRs = sJT_result; 

} 

finally { 

sJT_execCtx.rel easeStatement () ; 

} 

try { 

sql j .runtime. ref .Resul t Set I ter Imp 1 .checkCol umns( sJT_rtRs , 1) ; 

if (! sJT_rtRs.next() ) 

{ sql j .runtime. error. Runt imeRef Errors .rai se_N0_R0W_SELECT_INT0() ; } 

countl = sJT_rtRs .getLongNoNul 1 (1) ; 

if ( sJT_rtRs.next()) 

{ 

sql j .runtime. error. Runt imeRef Errors .rai se_MULTI_R0W_SELECT_INT0() ; 

} 

} 

finally 

{ 

sJT_rtRs.close() ; 

} 

} 

J j ************************************************************ 

/*@1 i nei nfo:user-code*//*@l ineinfo: 51^76*/ 


Figure 249. SQL] Code after Translation: Select Without Result S& 
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Deployment of an SQLJ Servlet to WebSphere 

Moving the SQLJ servlet is relatively simple. PI ace the servlet files in the 
same directory as the other servlets on your machine. It is important that 
you remember to move all of the class fi les that are output from the 
translator. Any iterators you had will create their own class file. A ProfileKey 
class, which is an index to your profiles, and the actually profile (.sar file) will 
also be created and must be accessi ble by the servlet. The servlet directory 
containing your classes is a natural place to put both of these files. 

You should also make sure that the proper class paths are listed in thej ava 
Engine setup (Figure 250). You must be sure to add thefiles: 

c:\sql lib\java\db2java.zip 
c:\sqll ib\java\runtime.zip 
c:\sqlli b\java\sql j . z i p 



Figure 250. WebSphere Application Server: J ava E ngineSetup 
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SQLJ Servlet Output 

The servlet is now ready to run under WebSphere. The output is shown in 
Figure 251. 



Figure 251. 


Output of SQLJ Servlet E mployees in Department Example 
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Appendixes 
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A Odds and Ends 


I n this chapter we describe the various odds and ends that we encountered 
while working with the different database systems. 


©Copyright IBM Corp. 1999 


263 




Different Mapping of SQL Types 

After creating the database and inspecting it with the tools to build query 
statements, we discovered that the databases differ in the way they interpret 
types. To see this, it is sufficient to compare the mapping of the employee 
table for DB2 (Figure 252), Oracle (Figure 253), and SQL Server (Figure 254). 

As you can see, mapping differs in those fields related to dates and to the 
SMALL I NT field. U nfortunately, this makes it impossible to use one meta 
data specification for the data access bean for all databases. 

This applies to code that depends on the I BM data access beans, that is code 
generated by the Studio Wizards, code generated by the SmartGuides of 
VisualAgefor J ava when using the Select bean, and also non-generated hand 
written code. 



Figure 252. Default Mapping for the E mpl oyeeTabl e i n DB2 
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Column 

Current data type 

Map to new data type 

ITSO. EMPLOYEE. EMPNO 

CHAR (Type 1) 

CHAR (Type 1) 


ITSO. EMPLOYEE. FIRSTNME 

VAR CHAR (Type 1 2) 

VARCHAR (Type 1 2) 

d 

ITSO.EMPLOYEE. MIDINIT 

CHAR (Type 1) 

CHAR (Type 1) 

d 

ITSO.EMPLOYEE. USTNAME 

VAR CHAR (Type 1 2) 

VARCHAR (Type 1 2) 

d 

ITSO.EMPLOYEE.WORKDEPT 

CHAR (Type 1) 

CHAR (Type 1) 

d 

ITSO.EMPLOYEE. PHONENO 

CHAR (Type 1) 

CHAR (Type 1) 

d 

ITSO. EMPLOYEE. HIREDATE 

TIMESTAMP (Type 93) 

TIMESTAMP (Type 93) 


ITSO.EMPLOYEE.JOB 

CHAR (Type 1) 

CHAR (Type 1) 

d 

ITSO. EMPLOYEE. EDLEVEL 

DECIMAL (Type 3) 

DECIMAL (Type 3) 


ITSO. EMPLOYEE. SEX 

CHAR (Type 1) 

CHAR (Type 1) 

d 

ITSO. EMPLOYEE. BIRTHDATE 

TIMESTAMP (Type 93) 

TIMESTAMP (Type 93) - 


ITSO.EMPLOYEE.S ALARY 

DECIMAL (Type 3) 

DECIMAL (Type 3) 

d 

ITSO. EMPLOYEE. BONUS 

DECIMAL (Type 3) 

DECIMAL (Type 3) 

d 

ITSO. EMPLOYEE. COMM 

DECIMAL (Type 3) 

DECIMAL (Type 3) 

■ 


Figure253. Default Mapping for the E mpl oyeeTabl e i n Oracle 


Column 

Current data type 

Map to new data type 

itso. EMPLOYEE. EMPNO 

CHAR (Type 1) 

CHAR (Type 1) 

a 

itso.EMPLOYEE. FIRSTNME 

VARCHAR (Type 1 2) 

VARCHAR (Type 1 2) 

d 

itSO.EMPLOYEE. MIDINIT 

CHAR (Type 1) 

CHAR (Type 1) 

- 

itso.EMPLOYEE. LASTNAME 

VARCHAR (Type 1 2) 

VARCHAR (Type 1 2) 

d 

itso.EMPLOYEE.WORKDEPT 

CHAR (Type 1) 

CHAR (Type 1) 

d 

itso.EMPLOYEE. PHONENO 

CHAR (Type 1) 

CHAR (Type 1) 

- 

itso. EMPLOYEE. HIREDATE 

datetime (Type 11) 

datetime (Type 11) 

♦ 

itso.EMPLOYEE.JOB 

CHAR (Type 1) 

CHAR (Type 1) 

- 

itso. EMPLOYEE. EDLEVEL 

SMALLINT (Type 5) 

SMALLINT (Type 5) 


itso. EMPLOYEE. SEX 

CHAR (Type 1) 

CHAR (Type 1) 

- 

itso. EMPLOYEE. BIRTHDATE 

datetime (Type 11) 

datetime (Type 11) 


itso.EMPLOYEE.S ALARY 

DECIMAL (Type 3) 

DECIMAL (Type 3) 

- 

itso. EMPLOYEE. BONUS 

DECIMAL (Type 3) 

DECIMAL (Type 3) 

d 

itso. EMPLOYEE. COMM 

DECIMAL (Type 3) 

DECIMAL (Type 3) 

d 



Figure254. Default Mapping for theEmployeein ODBC/ Sql Server 
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Correct Deployment of Enterprise Beans 

Because the deployment of enterprise beans is a somewhat difficult step, 

especially because very few error messages are thrown that could indicate 

what was wrong, keep the following rules in mind: 

□ For a BM P bean, deploy the EJ S file rather than the EJ B file in VisualAge 
forj ava.This preserves the mapping to the database. 

□ I n WebSphere, do not regenerate the bean, only redeploy it. 

□ Delete any unused containers (Entity and Session). 

□ Session containers must specify a valid DB2 database; also verify that the 
specified user I D may access the database. 

□ To complete the deployment process, you have to stop WebSphere, then 
stop the HTTP Server, and finally start the HTTP Server again, which 
should start up the WebSphere Servlet Service as well. 

□ Add memory to your computer; to use VisualAge for J ava and WebSphere 
we suggest 128MB minimum. 


Data Access Beans 

It seems that the data access beans do generally work better when the input 
and output types are not specified using classes, but using integer values of 
the j ava. sql. Types class. U nfortunately, this creates problems with the 
Wizards of WebSphere Studio, because they always generate 
Cl assN armed ass instead of Types.TYPE. 

According to IBM support, this is a known bug and is fixed as of version 1.1 of 
the data access beans. U nfortunately this version is neither part of 
WebSphere nor WebSphere Studio. Especially for WebSphere Studio, this is 
unfortunate because it makes the usage of Date fields impossible. 

The bug manifests itself in the following example: 

addColumn(" HI REDATE", java. sql .Date. class, Types. DATE); 
addColumn(" HI REDATE" , Types. DATE, Types. DATE); 

Thefirst call fails and throws a com.ibm.db. Data Exception (Not supported 
J ava class is specified in parameter field), but the second call works. 

The same problems appear with timestamps: 

addColumn("HIREDATE", java. sql .Timestamp. class, Types .TIMESTAMP) ; <== fails 

addCol umn ("HI REDATE" , Types .TIMESTAMP, Types .TIMESTAMP) ; <== works 
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WebSphere Studio 

When WebSphere Studio 3 beta 2 is used to create a servlet accessing a 
database, there is a little bug when using the option C reate page for when no 
data is returned (Figure 255). 



F i gure 255. WebSphere S tudi o Database Wi zard 

If this option is used, the Database Wizard creates a servlet class that 
catches a com.ibm.webtools.runtimeNoDataException. This exception is part 
of the file webtlsrn.jar, which is part of the WebSphere Studio distribution, 
but apparently it is not part of WebSphere Application Server. The result is 
that the servlet will not execute at all when published to the application 
server because it cannot find the exception class. 

One workaround is simply not to use this option, but this is not a solution 
when one would liketousethe servlets to update the database. 

Thesecond possibility issimplyto copy thej AR fileto the application server: 

from: c:\WebSphere\StudioBeta\l ib\AppServerV2\webtl srn. jar 

to: c:\WebSphere\AppServer\lib 

With this solution, the generated servlet works well. 
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B Special Notices 


This publication is intended to helpj ava developers develop enterprise 
applications with VisualAgefor J ava Enterprise Version 2 and IBM 
WebSphere, together with relational database systems. The information in 
this publication is not intended as the specification of any programming 
interfaces that are provided by VisualAgefor J ava Enterprise and IBM 
WebSphere. Seethe PUB LI CATI ONS section of the IBM Programming 
Announcement for VisualAgefor J ava Enterprise and IBM WebSphere for 
more information about what publications are considered to be product 
documentation. 

References in this publication to I BM products, programs or services do not 
imply that I BM intends to make these available in all countries in which 
IBM operates. Any reference to an I BM product, program, or service is not 
intended to state or imply that only I BM 's product, program, or service may 
be used. Any functionally equivalent program that does not infringe any of 
I BM 's intellectual property rights may be used instead of the I BM product, 
program or service. 

Information in this book was developed in conjunction with use of the 
equipment specified, and is limited in application tothose specific hardware 
and software products and levels. 
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IBM may have patents or pending patent applications covering subject 
matter in this document. Thefurnishing of this document does not give you 
any license to these patents. You can send license inquiries, in writing, tothe 
IBM Director of Licensing, I BM Corporation, North Castle Drive, Armonk, 
NY 10504-1785. 

Licensees of this program who wish to have information about it for the 
purpose of enabling: (i) the exchange of information between independently 
created programs and other programs (including this one) and (ii) the mutual 
use of the information which has been exchanged, should contact IBM 
Corporation, Dept. 600A, Mail Drop 1329, Somers, NY 10589 USA. 

Such information may be available, subject to appropriate terms and 
conditions, including in some cases, payment of a fee. 

The information contained in this document has not been submitted to any 
formal IBM test and is distributed AS I S. The information about non-IBM 
("vendor") products in this manual has been supplied by the vendor and IBM 
assumes no responsibility for its accuracy or completeness. The use of this 
information or the implementation of any of these techniques is a customer 
responsi bi I ity and depends on the customer's abi I ity to eval uate and 
integratethem into the customer's operational environment. Whileeach item 
may have been reviewed by I BM for accuracy in a specific situation, there is 
no guarantee that the same or similar results will be obtained elsewhere. 
Customers attempting to adapt these techniques to their own environments 
do so at their own risk. 

Any pointers in this publication to external Websites are provided for 
convenience only and do not in any manner serve as an endorsement of these 
Web sites. 

Any performance data contained in this document was determined in a 
controlled environment, and therefore, the results that may be obtained in 
other operating environments may vary significantly. Users of this document 
should verify the applicable data for their specific environment. 

This document contains examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples 
contain the names of individuals, companies, brands, and products. All of 
these names are fictitious and any similarity tothe names and addresses 
used by an actual business enterprise is entirely coincidental. 

Reference to PTF numbers that have not been released through the normal 
distribution process does not imply general availability. The purpose of 
including these reference numbers isto alert IBM customers to specific 
information relative to the implementation of the PTF when it becomes 
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avail able to each customer according to the normal IBM PTF distribution 
process. 


The following terms are trademarks of the I nternational Business Machines 
Corporation in the U nited States and/or other countries: 


IBM ® 

AS/400 

CICS 

OS/390 

S/390 

ThinkPad 

WebSphere 


DB2 

OS/2 

OS/400 

TeamConnection 

VisualAge 


The following terms aretrademarks of other companies: 

C-bus is a trademark of Corollary, I nc. in the United States and/or other 
countries. 

J ava and all J ava-based trademarks and logos aretrademarks or registered 
trademarks of Sun M icrosystems, I nc in the U nited States and/or other 
countries. 

Microsoft, Windows, Windows NT, and the Windows logo aretrademarks of 
M icrosoft Corporation in the U nited States and/or other countries. 

PC Direct is a trademark of Ziff Communications Company in the U nited 
States and/or other countries and is used by I BM Corporation under license. 

ActionMedia, LAN Desk, MMX, Pentium and ProShare aretrademarks of 
I ntel Corporation in the U nited States and/or other countries. 

UNIX is a registered trademark in the United States and/or other countries 
licensed exclusively through X/Open Company Limited. 

SET and the SET Logo aretrademarks owned by SET Secure Electronic 
T ransactions LLC. 

Other company, product, and service names may be trademarks or service 
marks of others. 
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C Related Publications 


The publications listed in this section are considered particularly suitable for 
a moredetailed discussion of thetopics covered in this redbook. 
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International Technical Support Organization 
Publications 

For information on ordering these I TSO publications see "How to Get ITSO 

Redbooks” on page 277. 

□ Developing an e-Busi ness Application for the WebSphere Application 
Server, SG 24-5423 

□ VisualAgefor J ava Enterprise Version 2: Persistence Builder with GUIs, 
Servlets, and J ava Server Pages, SG 24-5426 

□ WebSphere Application Servers - Standard and Advanced, SG24-5460 

□ Enterprise J avaBeans Development Using VisualAgefor J ava, SG24-5429 

□ J ava Application Development for CICS: BaseServicesand CORBA Client 
Support, SG 24-5275 

□ UsingVisualAgeSmalltalkObjectExtender, SG24-5258 

□ Visual Age for J ava E nterprise Version 2: Data Access Beans - Servlets - 
CICS Connector, SG 24-5265 

□ Programming with VisualAgefor J ava Version 2, SG24-5264, published by 
Prentice Hall, ISBN 0-13-021298-9, 1999 (IBM form number SR23-9016) 

□ Visual Age for J ava E nterprise Version 2 Team Support, SG24-5245 

□ Using Visual Age for J ava E nterprise Version 2 to Develop CORBA and 
EJ B Applications, SG 24-5276 

□ VisualAgeJ ava-RM I -Smalltalk, TheATM Sample from A toZ, SG24-5418 

□ U si ng Visual Age U ML Designer, SG24-4997 

□ Application Development with Visual Age for J ava Enterprise, SG24-5081 

□ Creating J ava Applications with NetRexx, SG24-2216 

□ Unlimited Enterprise Access with J ava and Visual Age Generator, 

SG 24-5246 

□ From Client/ Server to Network Computing, A Migration to J ava, 

SG 24-2247 

□ Connecting theE nterpriseto thelnternet with MQSeries and VisualAgefor 
J ava, SG 24-2144 
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Redbooks on CD-ROMs 

Redbooks are also availableon thefollowing CD-ROMs. Click theCD-ROMs 
button at http://www.redbooks.ibm.com/ for information about all theCD-ROMs 
offered, updates and formats. 


CD-ROM Title 


Collection Kit 
Number 


System/390 Redbooks Collection SK2T-2177 

Networking and Systems Management Redbooks Collection SK2T-6022 


Transaction Processing and Data Management Redbooks Collection SK2T-8038 
Lotus Redbooks Collection SK2T-8039 

Tivoli Redbooks Collection SK2T-8044 

AS/400 Redbooks Collection SK2T-2849 

Netfinity Hardwareand Software Redbooks Collection SK2T-8046 

RS/6000 Redbooks Collection (BkMgr) SK2T-8040 

R S/6000 Redbooks Collection (PDF Format) SK2T-8043 

Application Development Redbooks Collection SK2T-8037 

IBM Enterprise Storage and Systems Management Solutions SK3T-3694 


Other Publications 

These publications are also relevant as further information sources: 

□ Developing J avaBeans with Visual Age for J ava Version 2, SC34-4735 

□ Design Patterns: Elements of Reu sable Object-Oriented Software, Erich 
Gamma, Richard Helm, Ralph J ohnson, andj ohn Vlissides, published by 
Addison-Wesley Professional Computing Series, ISBN 0-201-63361, 1995 
(IBM form number SR28-5629) 
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How to Get ITSO Redbooks 


This section explains how both customers and IBM employees can find out about ITSO 
redbooks, redpieces, and CD-ROMs. A form for ordering books and CD-ROMs by fax or 
e-mail is also provided. 

• Redbooks Web Site http://www.redbooks.ibin.coni/ 

Search for, view, download or order hardcopy/CD-ROM redbooks from the redbooks web 
site. Also read redpieces and download additional materials (code samples or 
diskette/CD-ROM images) from this redbooks site. 

Redpieces are redbooks in progress; not all redbooks become redpieces and sometimes just 
a few chapters will be published this way. The intent is to get the information out much 
quicker than theformal publishing process allows. 

• E-mail Orders 


Send orders by e-mail including information from the redbooks fax order form to: 


In United States 
Outside North America 


• Telephone Orders 

United States (toll free) 
Canada (toll free) 
Outside North America 


• Fax Orders 


e-mail address 

usi b6fpl (Si bmmai I .com 

Contact information is in the "How to Order" section at this 
site: 

http://www.elink.ibmlink.ibm.com/pbl/pbl/ 


1-800-879-2755 
1-800-1 BM-4YOU 

Country coordinator phone number is in the "How to Order" 
section at this site: 

http://www.elink.ibmlink.ibm.com/pbl/pbl/ 


United States (toll free) 
Canada 

Outside North America 


1-800-445-9269 

1-403-267-4455 

Fax phone number is in the "How to Order" section at this site: 
http://www.el ink. ibml ink.ibm.com/pbl / pbl / 


This information was current at the time of publication, but is continually subject to change. 
The latest information may be found at the redbooks Web site. 


IBM Intranet for Employees 

IBM employees may register for information on workshops, residencies, and redbooks by 
accessing the IBM I ntranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO 
Mailing List button. Look in theMaterials repository for workshops, presentations, 
papers, and Web pages developed and written by the ITSO technical professionals; click 
the Additional Materials button. Employees may access MyNews at http://w3.ibm.com/ for 
redbook. residency, and workshop announcements. 
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IBM Redbook Fax Order Form 

Please send me the following: 

Title Order Number Quantity 


First name 

Last name 


Company 

Address 

City 

Postal code 

Country 

Telephone number 

Telefax number 

VAT number 

□ 1 nvoi ce to cu stomer n u mber 




□ Credit card number 


Credit card expiration date Card issued to Signature 

V\fe accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not 
available in all countries. Signature mandatory for credit card payment. 
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List of Abbreviations 


unit of work 

uniform resource locator 
World Wide Web 


AWT 

Abstract Windowing Toolkit 

CGI 

Common Gateway 1 nterface 

CORBA 

Common Object Request Broker 
Architecture 

DBMS 

database management system 

DLL 

dynamic link library 

GUI 

graphical user interface 

HTML 

Hypertext Markup Language 

HTTP 

H ypertext T ransfer Protocol 

IBM 

International Business Machines 
Corporation 

IDE 

integrated development 
environment 

ITSO 

International Technical Support 
Organization 

JAR 

J ava archive 

JDBC 

J ava Database Connectivity 

JDK 

J ava Developer's Kit 

JFC 

J ava Foundation Classes 

J SDK 

J ava Servlet Development Kit 

JSP 

J ava Server Pages 

J VM 

J ava Virtual Machine 

ODBC 

Open Database Connectivity 

PIN 

personal identification number 

RDBMS 

relational database management 
system 

RMI 

Remote M ethod 1 nvocation 

SQL 

structured query language 

TCP/IP 

Transmission Control 

P rotocol /I nter n et P rotocol 


API 

application programming interface 

uow 

ASP 

Active Server Pages 

URL 

ATM 

automated teller machine 

WWW 
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Index 


A 

access control list 238 
alias 4 
Apache 4, 5 
Application Server 
see WebSphere 
assembly stages 196 

B 

bean managed persistence 132, 164 

c 

class path 129 
J ava 60 

Persistence Builder 130 
VisualAgefor J ava 48 
WebSphere 49, 129 
WebSphere Studio 181 
configuration 
security 241 
VisualAgefor J ava 10 
WebSphere 6 
WebSphere Studio 181 
publishing 194 
connection 

data access beans 89 
J DBC 83, 112 
connection manager 65, 84 
J DBC 69 
sample 70 

data access beans 98 
DB2 77 
Oracle 79 
SQL Server 79 
servlet interaction 66 
connection pool 67, 68, 84 
container managed persistence 132, 133 

D 

data access beans 81 
EJ B persistence 167 
output tailoring 96 


sample 

connection manager 98 
DB2 86 
Oracle 95 
SQL Server 95 
servlet sample 86 
SQL types 266 
Database Wizard 188,200 
datastore 

activation 126 
DB2 

application driver 44 
Client Application Enabler 44 
Command Window 24 
Control Center 22 
create database 23 
data load 26 
fixpack 22, 247 
installation 22 
J DBC 44, 82 

applet server 45 
drivers 26 

network driver 45, 56 
sample 

connection manager 77 
data access beans 86 
EJ B 170 
J DBC 56 

Persistence Builder 112,127 
SQLJ 251 

WebSphere Studio 183 
Software Developer's Kit 250 
SQL types 264 
SQLJ 22, 249 
table creation 24 
DBNavigator bean 82 
debugging 

VisualAgefor J ava 210 
directory service 238,245 
document root 4 


EJ B 

container 132,133,166 
Development Environment 
VisualAgefor J ava 134 
fields 138 
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generate code 143 
group 134 
mapping 142 
methods 139 
primary key 137 
sample 

DB2 133 
servlet 174 

server 132, 133, 143, 144 
test client 145 
enterprise bean 

application sample 160 
deployment 149, 177, 266 
servlet sample 153 
test 143 
test client 145 
EnterpriseJ ava Server 132 
EnterpriseJ avaBeans 
architecture 131 
see also enterprise beans 
Enterprise U pdate 10 
entity bean 132 

H 

home interface 132,146 
HTML 

visual composition 122 
HTTP Server 3, 152, 195 
installation 4 


import 

schema 112 
installation 

DB2UDB 22 
HTTP Server 4 
Oracle 27 
SQL Server 33 
VisualAgefor J ava 10 
WebSphere 5 
WebSphere Studio 181 
Internet Explorer 3 
iterator 254 
ITSO 

project 17 
user I D 23 

itso.wasdb.accessbean package 
itso.wasdb.connaccess package 


itso.wasdb.connmgr package 70 
itso.wasdb.ejb package 134 
itso.wasdb.ejb.client package 160 
itso.wasdb.jdbc package 53 
itso.wasdb.persist package 118 
itso.wasdb.persist.gui package 121 
itso.wasdb.persist. metadata package 121 
itso.wasdb.persist. Services package 120 
itso.wasdb.studio package 191 
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